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M ac developers depended on CodeWarrior to make the 
platform architecture shift from 68K to PowerPC 
processors. Now CodeWarrior does it again, speeding your 
transition to the next new operating system. CodeWarrior for 
Mac OS. Version 6.0 supports development for both OS X 


and Classic Mac operating systems from a single, powerful, 
award-winning Integrated Development Environment. 
Discover how CodeWarrior for Mac OS, Version 6.0 can 
help you realize your Mac development dreams. 
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“Without a doubt, the Premiere Resource Editor 
for the Mac OS ... A wealth of time-saving tools.” 

- Mac User Magazine Eddy Awards 

“A distinct improvement over Apple’s ResEdii. ” 

- Mae Tech Magazine 

'Every Mac OS developer should own a copy of Resorcerer. w 

- Leonard Rosenthal, Aladdin Systems 

“Without Resorcerer, our localization efforts would look like a 
Tower of BabeL Don f t do product without itT 

- Greg Gala nos f CEO and President , Metrowerks 


a Resorcerer’s data template system is amazing .* 

- Bill Goodman f author of Smaller Installer and Compact Pro 

“Resorcerer Rocks! Buy it, you will NOT regret it" 

— Joe Zobkiw, author of A Fragment of Your Imagination 

“Resorcerer will pay for itself many times over in saved time and effortT 

- MacUser review 

“The template that disassembles PICTf is awesome!" 

Bill Steinberg, author of Pyro! and PBTools 

u Re sorcerer proved indispensible in its own creation!” 

— Doug McKenna , author of Resorcerer 



03k 

W 





Version 2.0 


The Resource Editor for the Mac ™ OS Wizard 


ORDERING INFO 


Requires System 7.0 or greater, 
1.5MB RAM, CD-ROM 

Standard price: $256 (decimal) 
Website price: $128 - $256 
(Educational* quantity, or 
other discounts available) 

Includes: Electronic documentation 
60-day Money-Back Guarantee 
Domestic standard shipping 

Payment: Check, PC s, or Visa/MC 
Taxes: Colorado customers only 

Extras (call, fax, or email us): 

COD, FedEx, UPS Blue/Red, 
International Shipping 

Matuem^sthettcs, TNC. 

PO Box 298 

Boulder, CO 80306-0298 USA 
Phone: (303) 440-0707 
Fax: (303 ) 440-0504 
resorcerer@mathem aesthetics.com 


* Very fast* HFS browser for viewing file tree of all volumes 

* Extensibility for new Re sorcerer Apprentices (CFM plug-ins) 

* New AppleScript Dictionary Oaete*) Apprentice Editor 

* MacOS 8 Appearance Manager-savvy Control Editor 

* PowerPlant text traits and menu command support 

* Complete AIFF sound file disassembly template 

* Rig-, little-, and even mixed-endian template parsing 

* Auto-backup during file saves; folder attribute editing 

* Ships with PowerPC native, fat, and 68K versions 


- Fully supported; it's easier, faster, and more productive than ResEdit 

* Safer memory-based, not disk-file-based, design and operation 

* All file information and common commands in one easy-to-use window 

* Compares resource files, and even edits your data forks as well 

* Visible, accumulating, editable scrap 

* Searches and opens/marks/selects resources by text content 

* Makes global resource ID or type changes easily and safely 

* Builds resource files from simple Rez-like scripts 

* Most editors DeRez directly to the clipboard 

* All graphic editors support screen-copying or partial screen-copying 

* Hot-linking Value Converter for editing 32 hits in a dozen formats 

* Its own 32-bit List Mgr can open and edit very large data structures 

* Templates can pre- and post-process any arbitrary data structure 

* Includes nearly 200 templates for common system resources 

* TMPLs for Installer, MucApp, QT, Balloons, AppleEvent, GX, etc. 

* Full integrated support for editing color dialogs and menus 

* Try out balloons, ‘ictb's, lists and popups, even create C source code 

* Integrated single-window Hex/Code Editor, with patching, searching 

* Editors for cursors, versions, pictures, bundles, and lots more 

* Relied on by thousands of Macintosh developers around the world 


To order by credit card, or to get the Latest news, bugfixes, updates, and apprentices, visit our website... 

www.mathemaesthetics.com 
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VIEWPOINT 


By John C I Isoi Daub, Contributing Editor. Austin, Texas ISA 


What We C\js Lfarn From OpenBSD 

Like die whole of the Mac community, I am eagerly awaiting die 
arrival of Mac OS X, Not only w ill we have the best user experience 
of any operating system available today, but well finally have the 
muscle under the hood to go places the Mat has never been before. 
Coupled with hardware like the dual processor Power Mac G4 and 
the Power Mac G4 Cube, we re now ready to tackle the big server 
and business markets, right? Well, almost. 

During a particular daily pilgrimage u> the Slashdui website, I 
liappencd ujxhi a few aiticles ukul OpenBSD, From the OpcnHSD.ufg 
web site: “The OpenfiSD project produces a free, multi pkuform, 
4.4BSD-based Unix-like operating system. Our efforts emphasize 
portability, standardization, correctness, proactive security, and 
integrated cryptography." 'fhe security aspect of OpenBSD is what sets 
it apart from other operating systems; the OpenBSD project aspires to k 
numkr one in the industry for security, it they’re not already. 

Sfq re hy Default 

Mac users have long Ixxisted aixnil the Mac OS’s “security by 
default". When the US. Army's w ebsites were cracked June 2K, 1999, 
the Army responded by switching to Maes. Events like these allow 
Mae users to pul a feather in their cap. The Mac OS isn’t uneiackable. 
but lacking a command line and not being Windows nor 1 nix-like, 
many of the potential vulnerabilities o! an operating system simply 
don't exist. Hut wail a minute! Doesn’t Mac OS X have a command 
line? And what about the BSD layer and other U nix-isms present in 
Mac OS X? linn, Perhaps it's time for the Mac community to pay 
more attention to security issues. A good place to start, especially for 
us developer, is to take a cue from the OpenRSD project. 

One aspect of OpenRSD s purity stances Ls to lx* "secure by 
default". 'Dial mems the operating system is shipped with all non- 
essential seivkvs disabled. As a user liecomes more familiar with the 
system and desires to utilize more services, he or she will have to learn 
about the prexess and what needs to k enabled Hqxtfully by going 
lJ in ju^U this process, the user is more likely to leant about security 
issues, By educating a user in a safe and forgiving environment, not only 
drx*s it lead to a smarter user, but hopefully helps him or her avoid 
learning alxiul security the Bud was 

Granted OpenBSD x tatgei audience is different than Mat OS's, so 
it's likely what services the two operating systems would provide by 
default would lx- different as well. But by the same token, the tuiget 
audience for the Mac OS Is more likely to lie less computer savvy than 
your typical OpenBSD user With bixmdl xind Internet access growing 
exponentially and more and more people getting online (retail those 
LMac sales numkrsL it liecomes even more critical to the Mat user 
experience to provide a safe and secure environfiienl right out of the 
box, Rcmemkr, according to that LMac commercial there are only three 


(well, two) easy steps to gel on tlx; Internet: plug in, gel connected; 
there s no step throe. Being a security exjxm Ls not one of the steps. 

Improve Code Quaiiiy 

How many times in the past few years have you heard about 
security problems due to 'buffer overflow?" Ultimately it's just a 
“simple coding error," but how many of these errors could have 
been caught and fixed if greater emphasis was placed on quality 
of code instead of hacking in twenty new' features and shipping 
before the end of the quarter? The potential cost of that simple 
error could he far greater than the costs involved in having a solid 
code review and auditing process in place. 

The proactive code auditing process utilized by the 
OpenBSD project isn't as much alxJUt looking for security holes 
as it is looking for coding bugs. They simply perform an extensive 
analysis of every source file. If new problems are found, then 
previously audited code gels reviewed again with the new 
problems in mind. Auditing the code multiple times by multiple 
people helps to improve not only the security of the code, but 
also the overall quality of the code. It s a nice double-benefit, 

t understand the realities of software development: budgets, 
marketing requirements, schedules running over, king severely 
understaffed. Unfortunately due to these realities, quality of code is often 
sacrificed, which results in less than optimal product quality. And if you 
ship a shoddy product fcx> many times, people will stop buying your 
products and lost* faith in your company. Hie OpenRSD project's focus 
on quality allows them to pnx'laim at lire top of their website that its 
been throe years without a remote hole and two years without a local 
hole in the default install. That’s ilie sort of quality consumers are staiting 
to expect these days. Instead of making a fuss over how Mac OS X won t 
crush if one application crashes, why dorit we just have applications that 
don’t crash in the firsi place? We won't k able to hide khind our 
discturners and licensing agreements forever. 

So What Cajv We Learn? 

The Mac OS X public beta should k released by the time you 
read this, ff Apple has already taken steps towards being secure by 
default, all the better! If not, il is a kUu so that means there's time 
lo fix it. But this isn't just a call for Apple to do something; this is a 
cal) to you to rethink your assumptions and consider the implications 
that come with our new r OS paradigm. Every line of code needs to 
k written and reviewed with security and quality in mind. 

IF we want Apple, and hence our own businesses, lo grow and 
Nourish in the server and business markets, we need to think 
different from all the other players in that field, Except perhaps the 
OpenRSD project; their stance on security and quality is w here we 
need to start thinking the same, Ml 


John C, l>auh qxmds his days working as a developer for Aladdin Systems. Inc. currently working on the Stuffti Deluxe team. John spends his nights 
as he always tkxs: playing with his wife and kids. You cart contact John at hsoE@hsoi.mm. 


Thanx to James Chamkriain, Carl Constantine, Ron Davis, and Jim & Mary Ellen Lee for their input; and to Jessica for being such a sweetie, :■) 
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Question: Is MacHASP USB* a 
software security key or a 
sales tool? 

Answer: It's both! 

MacHASP USB is the world's first 
software protection key for the 
iMac. It gives you sophisticated 
license enforcement and compre¬ 
hensive protection against illegal 
use... in other words, real security. 

Then it gives you a big selling 
advantage. 

With MacHASP USB, you can 
license multiple software modules 
and applications. You can instantly 
unlock or upgrade them in the 
field. Plus you can freely distribute 
demos. 

Bottom line: MacHASP USB locks 
out illegal users and unlocks your 


full sales potential - without 
getting in anyone's way. Call now 
to request a Developer’s Kit and 
our newly published guide to USB 
features and benefits. 

‘For all USB-equipped Macs running an OS 
with USB support. Fully compatible with the 
ADB version of MacHASP. 


USA: 1-800-223-4277 
2 12-564-5678 
Inti: 972-3-6362222 

www.aks.com/mt 

ALADDIN 

KNOWLEDGE SYSTEMS LTD 


Mac software protection provider, Micro Macro Technologies, becomes part 
of Aladdin, giving its customers even better service from the number one name. 
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STARTED 


By John C. Welch 


Mac World New York 2000 


The Network Manager's 
eye view 

Wf.uxime To Thf, Show 

Tire New York Mac Work I Exjx> was a 
ground breaking show in many ways, 
Firstly, we have the attendance figure of 
61.250 attendees. While well below this 
year's San Francisco number of over 
85,000 attendees, it was a third more 
people than last year's New York 
MacWorld Expo, and well over the best 
figures for the best of the fabled Boston 
MacWorld Expos. A jump in the numbers 
like this is good for many reasons, but one 
of the important ones is that it's a sign that 
the New York move is finally picking up 
ihe numbers it needs to stand on its own, 
without being compared to shows from 
the Boston heyday. Attendance numbers 
like this year’s also means that vendors 
who may have previously ignored New 
York for the larger San Francisco show w ill 
think twice about that next year. Finally, 
for the first time, there were no huge 
empty areas of show' floor, noi-so-deverly 
hidden behind partitions* 

Keynote 

But enough cheerleading, whal about 
the show itself? Well, from my point of 
view, it was excellent all the way around. 
The keynote was, as usual, an example of 
showmanship at its finest. Steve Jobs' 
famed Reality Distortion Field was 
working lb usual magic r although 
considering the state of Apple tile lasL few 


years, it no longer needs to work quite as hard. The hardware 
announcements were welcome indeed. As an administrator, 1 am 
very pleased to no longer have to automatically toss out the 
standard Apple mouse and keyboard that comes with the Macs 
we buy* And. although this may sound unusual for a corporate 
environment, the fact that the new mouse is very pleasing to the 
eye is a bigger bonus than you might think. 

The announcement of the multi-processor G4 Macs was 
not that unusual to anyone who saw the demo of them at the 
Apple World Wide Developer Conference this past May. This 
was essentially a repeat of the initial demo of the CA at the 
WWDC in 1999, and then the release not long afterwards. 
Although many will point out that the current MacOS catTt 
handle multiple processors, that is not completely accurate. 
Apple has done a lot of work with the capabilities of the MP 
libraries in the current MacOS, especially with low-level tasks. 
Any developer taking advantage of these libraries should notice 
a definite improvement in performance on the MP Macs, This is 
also important for the upcoming public beta of MacOSX. By 
having MP Macs out in the hands of users prior to the beta, the 
radically improved MP capabilities of CSX will become 
immediately evident to Mac users, and this will help drive sales 
of not only MP Macs, but of 05X when it is released, 1 was 
surprised to see that Apple was not only making Ml 1 a standard 
feature of the mid-range and high-end G4 towers, but that they 
were able to do it for the same price as the Uniprocessor Macs, 
In essence, Apple is giving us a buy one. get one free' deal on 
the second CPU, and that is not a bad deal. 

I'm also excited about the MP G4 models for more 
immediate reasons. The company I do most of my work for is a 
.scientific firm* We make heavy use of Unix, multiple processors, 
and applications like Research System's IDL, which is a scientific 
image processing application. This type of application makes 
good use of additional processors when run under an operating 
system that supports 5MP property. Considering how expensive 
large-scale compute servers can be. the ability to have that level 
of processing c apability on a scientist's desk for around $3000 
has not only me, but many of my users eagerly awaiting the 


John Welch <jwddi©aerxom> is the Mac and PC Administrator for APR Inc., a weather and atmospheric science company 
in Cambridge, Mass. He lias over fifteen years of experience at making computers work His specialties are figuring out ways 
to make the Mac do what nobody thinks it can, and showing that the Mac is the superior administrative platform* 
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public beta of OSX T and the next round of Mac purchases. Since 
we are a scientific firm we also have network data needs that 
would be coasidered insane by anyone who isn't a Photoshop 
pro. When you are dealing with atmospheric models, the data 
.sets that support these models can easily approach, and often 
exceed Lhe gigabyte size range. So finding out that Apple is 
making Gigabit Ethernet standard equipment for the new G4 
Towers turned my smile up yet another notch, 

The new iMacs were, as always a crowd pleaser The 
new colors are rich and vibrant, but somehow more dignified 
than the previous flavors, The new pricing structure is 
appealing to a corporate environment as well. To be able to 
get an iMac with firewire, VGA mirroring, (a very welcome 
new iMac feature), 192MB of RAM, the three year extended 
warranty, a USB Zip and Super Drive for under $1700 makes 
buying one almost a no-brainer. Even when you add in 
things like Qffice98 t and the standard utilities and packages 
we use, we are still talking about a silent full-featured 
corporate computer for under $2500. Considering that 
corporate price points are often in the $2500 to $3000 range, 
the new iMacs nail this particular sweer spot dead on. It's 
remarkably coincidental how a company that is constantly 
saying they have no interest in the corporate enterprise is 
making some of the best corporate computers around. Or 
maybe home users do have a desperate need for Wake-On- 
LAN that none of us I.S.-types have figured out yet. 


1 said the iMacs were almost a no-brainer for die corporate 
crowd, only I because there is one other Mac that is even Ixater 
suited for this arena: The Cube. True, it's not expandable, and 
you can’t put in a different video card, and ii has only space for 
one hard drive, and all peripherals have to be external. 1 still 
think this object d’art is going to be a big seller in the corporate 
area. First of ah, it’s gorgeous, and I mean in a Porsche/Ferrari 
kind of way. This thing just seems to ooze coolness* It looks like 
it should be on a shelf with other ridiculously expensive knick- 
knacks in a house on a prime-time soap opera. 3 can't think of 
a better computer, especially with one of the new flat-panel 
LCDs to pur on a desk that is in an open area, or a receptionist's 
desk. The Cube is just, well, phat. Secondly, it's silent Not quiet, 
but almost completely -without noise. The hard drive is the only 
inherent noise coming from the Cube, and that is low enough 
to be ignored. For those of you who don’t understand why this 
is important, think about the difference in your office or cubicle 
the next time you have to turn your computer off. 1 have a 
Beige G3 server, an external RAID box, and an 18-tape Digital 
Linear Tape autochanger in my office. Believe me. the thought 
of getting rid of any one of those nolsemakers makes me smile. 
Now think about a corporate cube farm full of nice big Pentium 
towers, each with the standard two or three fans. Now imagine 
all that noise gone, to where you can hear the mouse clicks 
from a cubicle almost at the other end of the room, That is a 
cube farm full of Cubes; beautiful T Isn’t it? 



MPEG-4 Multimedia Streaming - the Internet's Next Step 


We Invite you to join us at e-Vue, Inc. to create the MPEG-4 multimedia streaming 
products and services that are destined to revolutionize the Internet MPEG-4 Is a 
brand new ISO standard that, unlike all prior standards, was specifically developed to 
provide web-based multimedia content delivery and interactivity* e-Vue, Inc. is a 
pre-IPO Sarnoff Corporation spin-off chartered to commercialize Samoffs extensive 
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While I will acknowledge that the Cube is totally 
Inappropriate for .someone who needs multiple processors, or 
specialized PCI cards, or for many server needs, the truth is, 
the vast majority of corporate users never add cards, never 
upgrade video cards, never do anything LhaL the' Cube cannot 
handle with ease. Considering how often people end up 
putting minitowers on their desktops, just because having to 
reach under their desk to get to the CD drive, or die Zip drive 
is such an annoyance, the size of die Cube is also going to be 
a big draw for the corporate crowd. Again, for a company 
totally disinterested in the corporate market, die Cube is one 
heck of a corporate computers. Apple’s protestations here 
remind me of the "Brutus is an honorable man” speech from 
Julius Caesar, 

That is not to say I found no shortcomings from the new 
hardware. 1 was dismayed to see Apple jumping to a brand 
new monitor connection with no w r ay around the new system 
for those looking to combine older monitors with newer Macs 
and vice-versa. This is a temporary annoyance at best though, 
because I can already hear the peripheral companies firing up 
the VGA to ADC convener production lines. Still, it would 
have been nice to have an announcement to that effect. 

the final bit of interesting keynote news was of course, 
OSX. Not the Aqua demo, (and that's what these are, Aqua 
demos, Outside of the developer community, I highly doubt 
that 90% of the Mac user community has seen any pan of 
OSX other than Aqua), but rather the public beta news. The 
September time frame is not a hideous delay, and if it means 
a better beta experience for all, then I see it as a good thing. 
OSX still looks to be on track for the January/Early 2001 
commercial release, and as long as that doesn't slip by more 
than a few r months, OSX should be still considered to he 
close to on time. Were I to be a cynic, I would say that by 
having a few million users who are living with, and happy 
with GSX, the initial sales of the new OS should be a hit right 
away, as those folks are not going to warn to go back to 9 X 
when their beta copies expire. But LhaL would be cynical 

The Rest of the Show 

Bui the keynote is only the more visible part of 
Mac World Expo, and only the beginning. There is a whole 
show floor, and three days of sessions that are of use to 
almost anyone. 

Products 

The first product of MaeWorld LhaL jumped out at me 
hasn’t been released yet. That was the announcement by 
Tenon Intersytems of a Full featured X Window application 
for OSX. This is a major announcement for the new OS, one 
that will help it gain real acceptance in the Unix community 
at large. X Window is the way that Unix computers can share 
applications that have a graphical interface with multiple 
users. This is not the same as products like VNC or 
Timbuktu. Those products are remote control applications, 


allowing you to take almost physical control of a remote 
computer, and use it almost as if you were sitting at that 
machine’s physical keyboard. What the X Window System, 
(its proper name) allows is for multiple users to log into a 
single computer, and use a single application at the same 
time. The code in the application executes on the remote 
computer, and only screen, mouse, and keyboard data is sent 
between machines. There are X Window applications 
available for almost every computer system on the market, 
Ihil it is especially important in rhe Unix world, as X is the 
primary means of running applications with a graphical 
interface. X is essentially a client-server display model, 
although its use of those terms can be a bit confusing. 
Essentially, Lhe display functions are parL of Lhe X server, and 
the applications running, and sending display information to 
the X server are the X clients. These can be not just remote 
applications, buL applications residing on Lhe local hard disk 
of your computer. 

Until this announcement, the only way to run X on OSX 
was to use a Darwin port of the XFree86 X Window 
application, (ported by John Carmack of Id Software, among 
others). However, the lack of a commercial X Window 
system for OSX was a serious hindrance to OSX’s acceptance 
as a Teal 1 Unix-based OS. The Tenon announcement changed 
all that, What is just as important is that Tenon’s product will 
allow OSX to serve standard X Window applications to other 
remote machines, and lo the local user as well. This means 
that almost any BSD Unix application that is able to run on 
the version of BSD that is part of OSX, and can run on the 
G3 or G4 processor can run under OSX. This opens up a 
potentially huge library of applications that Mac users have 
had to run on other systems before. Especially for the 
Scientific and Technology market, or SciTech, full X 
capabilities for OSX is a serious point in the OS’s favor at 
companies and universities in that arena. Finally, the Tenon 
announcement also covered LhaL Lhey will include X 
programming libraries and utilities with the product. This 
means that OSX-based developers will be able to create 
applications that take advantage of die G3 and G4 
architectural advantages, but are available to anyone who 
can run X Window' applications on their computer. So a 
developer could easily create an OSX application that had 
the Aqua interface, and took advantage of OSX’s capabilities, 
and then with a little work, add in the capability for that 
same application to be run by almost any other computer 
platform in existence today. This is a huge step forward in 
compatibility for the Mac, and will have a very positive effect 
on lhe platform’s growth. 

Other products that caught my eye, although not to the 
same extent as Tenon’s included the SANcube, from MicroNet 
Technology. The SANcube is interesting as an initial 
implementation of a FireWire-based Storage Area Network, 
(SAN) device. The advantage to a SAN is that all storage on a 
SAN are independent of any host. That is, to get to disks on 
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a SAN, you just mount the drives in the SAN device. No need 
to have a file server with the disks attached to it. This allows 
for greater flexibility in that you can have multiple computers 
with different OS's accessing the SAN storage device. It can 
also improve reliability by decoupling network storage from 
network servers, which means the storage on a SAN only has 
to be a storage device, not a file server with an OS, and the 
problems that a server can cause. Unfortunately, due to 
limitations in the eurrem implementations of FireWire disk 
access methods, the disk access on the SAN cube is controlled 
at the volume level. This means that if you have only a single 
partition on a SAN cube, and 5 servers that are attached lo 
dial SANcube, only one server can have write access to that 
partition, all others can only read from it. MicroNet 
recommends that you try to create a partition for each 
computer attached to the SANcube, thereby giving each 
computer on the SAN a partition that they have full access to, 
and read access to al! the others. Hopefully, as FireWire is 
updated, this process will be able to happen at the file level, 
rather than the volume level. In any case, the SANcube still 
has great potential and usefulness, for things such as server 
farms, or situations where you only want one server to be 
able to write to a disk. 

Two of my favorite Mac networking and administration 
companies were al the Expo as well, namely Thursby Systems 
and Alsoft Thursby is the maker of such cross-platform 
compatibility products, such as DAVE, (for connecting Macs to 
a Windows network), MacNFS, (which gives Macs access to 
Unix files), and TSSNei, (to connect Windows machines to 
Mac Networks.) For those of us running multiple platform 
networks, Thursby’s products are the way we avoid the host 
of connectivity problems that multiple platforms sometimes 
create. Alsoft is the company that makes Disk Warrior, which 
is most likely the best drive recovery tool on the Mac market. 
All of these products are an essential part of any networking 
toolkit, and 1 have used them in various combinations over 
the years, and consider them to be an absolute requirement 
for my administrator’s toolkit. (On a side note, Chuck 
Goolsbee, keeper of the Mac-Manager’s list, gave Alsoft one 
of the hard to come by Mac-Manager’s list buttons, as a 
thanks for all the administrator’s keisters that DLskWamor has 
saved since its release. I was with Chuck when it happened, 
and considering how r often DiskWarrtor has saved 'dead' 
drives belonging to various executive types for me, 1 can't 
think of anyone more deserving.) 

Sessions 

As interesting and fun as the show floor is, there is yet 
another part of MacWorld Expo, that while not as glitzy, is a 
major part of the show for me, namely Lhe various Pro, User, 
and preshow sessions. 

The first set of sessions are the preshow conference 
workshops. These are seven hour, in-depLh classes that, cover 
everything from an introduction to Mac networking to Final 


Cut Pro. Not for the casual observer, the nice thing about the 
workshops is that with a seven hour timeframe, the presenters 
can really gel into the kind of detail that a normal show 
session wouldn’t allow them to. For me, the schedule is a 
little frustrating, so l tend to bounce between two or three 
different sessions. This year, I was having to decide between 
workshops on the Apple Macintosh Manager, a practical 
introduction to Mac Networking, and a getting started with 
AppleScript workshop. Although some might question the 
value of some of these workshops, especially the ones aimed 
at beginners, I would caution against that line of thought. 
These workshops, like almost al! the rest of lhe sessions aren’t 
taught by professional trainers, they are taught by the people 
in those fields, doing real work, and giving their experience 
back to you. As an example, the “Getting Started with 
AppleScript” session is run by Sal Soghoian, the AppleScript 
Product Manager for Apple, Even though I would consider 
myself to be a fairly competent AppleScript programmer, Sal 
always manages to give me something new, either in 
techniques, or looking at AppleScript in a different way, 1 
have found this to he true of almost every workshop T have 
ever attended, so again, 1 recommend thinking before 
dismissing a 'beginner' workshop. 

The next set of sessions are the Pro Conferences, and 
these are more targeted to a specific part of the Expo 
audience. The two that appeal to me as a network 
administrator are the Mac Manager Track, and the Macintosh 
Networking and Communications Track. The Mac Manager 
Track deals with, well, managerial issues. Things such as 
license compliance, backup strategies, an update on Apple’s 
Open Source initiatives, i was involved with two of the 
sessions in this track, one titled, “Becoming a Successful Mac 
Manager Part 1 — Business Issues”, and the other was titled 
“Scripting Mac Admin Tasks”. The first dealt with technic[ues 
for communicating within a company that is considering 
moving to a single platform, which is not the Mac, and the 
second dealt with how to integrate AppleScript into your 
network administration tasks. (Til withhold an opinion on 
these two, as I am somewhat biased.). Another session which 
was less technical than some others, but still very 7 useful was 
Lhe part II session to becoming a successful Mac manager. 
This part dealt with the nitty gritty of being a Mac !,S, 
manager* 'Things like operational procedures, hiring, internal 
promotion, turnover reduction, etc. All things that may not 
be as technically exciting as the new Macs, but are quite 
necessary to running a network or an IS department. Just to 
point out the experience of some of Lite presenters, one of 
the folks presenting this particular session was Chuck 
Goolsbee, who besides his role with the Mac-Manager s list, 
is also VP of Technical Operations for digital.forest, Inc, one 
of the biggest Mac web-hosting companies in the U.S. Again, 
where else can Mac managers get the benefits of that kind of 
experience, live, other than MacWorld? 
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In the Networking and Communications track, there 
were some very interesting sessions as well. The first one 
that jumps to mind is the Mac Networking Update session. 
One of the presenters for this one was Thomas Wcyer, the 
Networking and Communications Manager for Apple, This 
was invaluable to me, not only for an idea of the direction 
Apple is taking in this area, but for practical tidbits as well. 
One of the most useful was Tom explaining how to set up 
Air Port Base Stations to get proper channel separation so that 
you have cleaner signal on your wireless network. Or the 
explanation that the dot graph for the AirPort Control Strip 
module is a measurement of the signal-tu-noise ratio that you 
are currently getting for your AirPort device, not connection 
speed or signal strength as has been assumed. For those of 
us with wireless networks, these are small, yet invaluable bits 
of information, Other sessions included going from an 
AppleTalk lo a TCP/IP based nerwork, tips on tuning Open 
Transport, information on integrating MacOSX into existing 
networks, a Network Managers Forum, internet security 
advice, Virtual Private Network information, and how to use 
Kerberos authentication with the Mac OS. 

But again, it isn't just the session titles t)r subjects that 
make these invaluable, it's the fact that they are presented by 
people who either create the technology we use, or live with 
it, f was able to get more VPN information in 10 minutes of 
discussion with Bill Via has, who, in addition to being tile 
presenter for the VPN session, is also a Network Services 
Engineer for NASA's Jet Propulsion Laboratory. He deals 
with, and lives wirh cross-platform VPN issues every day, so 
his answers were based on experience and real world 
knowledge, instead of marketing brochures. The session on 
Comparing AppleSharelP with Windows NT and Windows 
2000 services was given by Paul Nelson, VP of Engineering 
for Thursby Software Systems, who are the makers of DAVE, 
a Windows networking stack for the Mac. So here you have 
a session given by someone who understands not only Mac- 
networking, but Windows networking at an extremely low 
level. Again, the experience brought to the table here is not 
going to be replicated by a professional trainer. My only 
complaint with the sessions is that I haven’t figured out how 
lo done myself, so i can't possibly make it to all of them. 

Conclusion 

in the end, even though MacWorld expo is billed as a 
consumer exposition, there is enough good information and 
products there for any network manager or administrator that 
deals wirh Macs to justify the cost. As well, if you have some 
knowledge that you would like to share, the Expo is always 
looking for new presenters and new ideas. I have yet to be 
disappointed by a MacWorld, and this one was no exception. 
From the keynote to the show- floor, to the sessions, there 
was enough there Lo keep my I.S. heart as happy as could 
be. The next MacWorld, in this country at least is in San 
Francisco, in January, 200b ! hope to see some of you there. 
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QUICKDRAW ID 
MEETS 

APPLESCRIPT 


By Tom Djajadiningrat 


3D For Free Using the Mac’s Standard Apps 


Converting raw 3D text 
files to QuickDraw SD's 
3DMFformat using 
AppleScript 


Summary 

Tliis article introduces you to the 
basics of 3D files in general and I he: 3D 
Metafile (3DMF), QuickDraw 3D's native 
3D format, in particular, it shows how 
you can use AppleScript to easily 
convert a raw 3D texL file into a 3DMF 
readable by the QuickDraw 3D Viewer 
or any other QuickDraw’ 3D compatible 
application. With this knowledge you 
can make hand-written data or data 
exported by a spreadsheet or database 
application suitable for visualisation as 
standalone 3D models. 

Introduction 

The combined power of the suite of 
goodies that comes standard with your 
Mac is really quite amazing. One such 
goody is the QuickDraw 3D Viewer, The 
QuickDraw 31 > Viewer makes it possible 
to do basic viewing of 3D models that 
are formatted as 3D Metafiles 0DMF\ 
QuickDraw 3D's native file format. Since 
the QuickDraw 3D Viewer is supported 
by SimpleTexL which comes standard 
with a Mac, files written in JDMF format 
can be viewed on any PowerMacintosh 
atoning QuickDraw 3D. Maybe you 


would like to visualise your spreadsheet or database data as 
standalone 3D models or perhaps you would like to write 
your own low-polygon count models by hand rather than use 
a 3D modeller. To achieve this you could make the 
spreadsheet or database application export complete 3DMFs. 
Often though it is quite awkward to get the formatting right. 
And though it is possible to write complete 3DMFs by hand, 
you of course w'unt to reduce repetitive chores, such as 
adding brackets, to save time and reduce errors. Here we take 
the approach of writing minimalistie 3D files which are then 
post-processed into 3DMF. So how do we do this post¬ 
processing? Enter two other Macintosh standard goodies: 
AppleScript and the SeriptMaker application. Although it is 
seldom used for this express purpose, AppleScript is actually 
quite good at reading and writing text files. Another nice 
feature of AppleScript is the case with which we can make a 
droplet: a script which performs certain actions on documents 
which are dropped on to it. This allows us to convert mtihiple 
files with the ease of drag and drop, 

QuickDraw JIVs 3DMF Format 

31) models can Ik* described using vertices and faces, A 
vertex is a point in 3D space described by x, y and z co¬ 
ordinates. A face is a polygon of which each corner point is a 
vertex. To prevent unpredictable results a face should be 
planar: all ils vertices should lie in one plane. Figure 1 shows 
a technical sketch of a table which consists of a square face (the 
table top) and eight triangular faces (the legs) Figure 2 shows 
the corresponding 3D model in the QuickDraw 3D Viewer, 


White walking about at the Geneva Motor Show,, Tom spotted a Japanese concept car in which a display dearly showed a 
Macintosh alert box w ith an error of Type 2. As he does not find the prospect of having to install and contiguity Linux for car 
navigation, car audio and engine management particularly appealing, he can't wait for the release of CSX. 
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// Like most Mac developers, 

// I easily spend 12 hours a day 

// staring at line after line of C++ code in tiny, 9 point Monaco. 

// Sometimes it makes my eyes feel like they're on fire. 

{ 

So the last thing f need is some 
fuzzy monitor that adds to my headaches. 

} 



/•*•••• begin excitement ••***•/ 

// That’s why I'm so jazzed about this SGI monitor. 

// Its ultra-high resolution = 1600 x 1024 and dpi = no, 

// giving me razor-sharp contrast. 

// And the high refresh rate is 
// perfect for poring through lines of code. 

// At first. I was amazed at the clarity, the fine details that emerged. 

\ 

It wat like teeing thinqt for the firtt time. 

1 

// Later, though, I learned to appreciate the wide aspect ratio (= 16:10], 
// with a generous 17.3 inches of viewing area. SGI’s I 600 SW 
// lets me have all my documents viewable at once, and it’s 
//a flat panel so it fits on my desk with room to spare. 


// From the moment I saw this thing I was hooked. You will be, too. 

( 

Especially when you find out 
how affordable it is. 

// * Check it out. 


/*•“•* end excitement *•***•/ 
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Figure L Technical sketch of a table. 



on an 


Figure 2 . The 31) model it! the QuickDraw 31) Viewer t 


Listing I shows a 3DMF file for this table. For our 
example we use the QuickDraw 3D mesh geometry, which is 
probably the easiest to understand way to describe a 3D 
model. The hash sign (*) marks a comment in a 3DMF* 
Everything on a line after a hash is ignored. Tlie 3DMF here 
consists of two parts. The first part is the header, 3DMetafile 
( 1 6 Normal too ), The second part is former I by a container 
which contains a single mesh object. Let's look at the header 
first. The header, formed by the first line of the file, tells us 
that we have a 3T> Metafile for QuickDraw 3D 1.6. The major 
version number is 1 and the minor version number is 6. The 
third field, Normal, is the type of 3D Metafile. The fourth field 
of the header, too, is a file pointer to a table of contents 
which is non-existent in this 3DMF. Don’t worry about the 


type of 3D Metafile and the table of contents parameters. You 
do not need to know their exact meaning Lo understand this 
article and later we explain where to read up on the full 
3 DM F s pec i Ftea r i< >n. 


Listing 1: a 3DMF file 

tabtejdf 

IDMfttafile ( 1 6 Normal loc> J 

#TMs is a table with a square top ;tnd four legs 
Container ( 

2Q ^number of vertices 
1 1.5 -1 #0 
-1 1.5 -1 #1 
-1 1,5 1 #2 
1 1.5 1 #3 
J 0 1 #4 
0♦9 1.5 0.6 #5 
0.9 !.5 0.9 #6 
0*6 1*5 0*9 #7 
1 0 -1 ffl 
0.6 1,5 -0*9 #9 
0.9 1,5 0*9 #10 

0.9 1.5 -0*6 #11 
1 0 -1 #12 
0*9 1*5 0.6 #13 

0.9 \ *5 0*9 #14 

-0.6 1.5 0.9 #15 

-1 0 1 #16 
-0.6 1.5 0*9 #17 
-0*9 1*5 0,9 #18 
0*9 1*5 0.6 #19 
9 #numfeer of faces 

0 #number of contours 

4 0 t 2 3 #0 
3 4 5 6 # t 
3 4 6 / #2 
3 8 9 ID #3 
3 8 10 11 #4 
3 12 13 14 #5 
3 12 14 15 #6 
3 16 17 18 #7 
3 16 18 19 #8 

) 

Container ( 

AttributeSet ( ) 

DiffuseCoior (1,0 1,0 0*0) #r g b 

) 

) 


Now let’s look at what takes place within the bracket of 
the container* The container contains a mesh and another 
container with a diffuse colour attribute in it. First the mesh 
description lists the number of vertices involved* In our case 
there are twenty vertices* What follows is a list of vertices 
which QuickDraw 3D sees as numbered from 0 to 19. Each 
vertex is described by three co-ordinates. For example, 
vertex number 0 has the co-ordinates x= J. y=1.5 and x--l. 
Next is the number of faces, eight in this case, followed by 
the number of contours. A contour is a polygonal hole in a 
face. Since there are no holes in our table the number of 
contours is 0. The mesh description finishes with the eight 
faces. The first number of a face description is the number of 
vertices involved in the face, the remaining numbers specify 
these vertices. For example, the square table top is face 
number 0, which has four corners formed by the vertices 0, 
1, 2 and 3- Finally, there is a diffuse colour attribute which 
applies to the whole mesh. Jt is specified in red, green and 
blue components, each ranging from 0.0 Lo 1.0. 
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The Raw 3D File 

It is very important to carefully consider what the raw 30 
file should look like before you start writing a script to convert 
it to 30MR If you yourself export the file or write it by hand you 
are of course in complete control. If someone else does this for 
you—say an expert in low-polygon count models — you want 
to make sure this person formats the file in such a way that 
makes life as easy on you as possible. On the other hand, you 
may wish to respect this person s way of formatting files. Listing 
2 shows an example of what a raw 3D file might look like, 'fhere 
are some differences between this raw 3D file and the 3DMF file 
we just discussed which make conversion pretty awkward, bur 
it is understandable why the formatting of the raw 3D file is 
convenient for the person who writes the file by hand. Because 
of the vertex and face labels on each line it is immediately dear 
whether one is in the vertices or faces section when quickly 
scrolling through the file. Because of the commas it is possible 
to put spaces between a minus sign and a co-ordinate so that the 
minus signs line up vertically. This makes it easier to spot co¬ 
ordinates with the wrong sign. Both vertices and faces start 
rather than end with their index number so that the indices line 
up too. A face line does not include the number of vertices 
which saves work and reduces errors. Careful deliberation with 
ail involved can safe much work and frustration. 

Listing 2: A raw 3D file 

table, lai 

Description;This Is a table with a square top umd four legs 


Vertices:20 


Vertex: 0, 

1* 1,5* 

-1 

Vertex: 1* 

-1* 

1.5* 

-1 

Vertex; 2. 


1.5* 

1 

Vertex: 3* 

1* 

1.5* 

1 

Vertex; 4, 

X. 

0. 

1 

Vertex: 5* 

0.9* 

1*5. 

0.6 

Vertex: 6, 

0.9. 

1.5. 

0.9 

Vertex: 7, 

0.6, 1.5, 

0.9 

Vertex: 8. 

1, 

0* 

-1 

Vertex: 9. 

0,6. 

1.5, 

-0.9 

Vertex:10. 

0.9. 

1.5* 

0*9 

Vertex:11 * 

0.9* 

1.5* 

0,6 

Vertex:12. 

-1* 0. 

-1 

Vertex:13, 

0.9 

* 1.5 

. -0.6 

Vertex:14. 

-0,9 

* 1.5 

, -0.9 

Vertex:15. 

-0.6 

. 1*5. 

, -0.9 

Vertex:16, 


0* 

1 

Vertex:17, 

-0.6 

* 1.5 

* 0.9 

Vertex:18, 

-0.9 

* 1.5. 

, 0.9 

Vertex:19, 

■0.9. 1.5. 

, 0.6 


Fares; 9 

Face: 0. 0, 1* 2* 3 

Face: 1, 4. 5. 6 

Face; 2, 4. 6* 7 

Face: 3. 8, 9, 10 

Face: 4# 8* 10, 11 
Face: 5, 12, 13, 14 

Face: 6* 12. 14, 15 

Face: 7 t 16. 1/, 18 

Face; B t 16. 18. 19 

ni£fuseColoJr:i.O 1.0 0.0 



Imagine that. Smart and beautiful. 
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AppleScript 

The next tiling we do is to write an AppleScript to convert 
the raw 3D text file to 3DME In the folder <your 
harddtsk>:Apple Extras:AppleScript you find the application 
ScriplMakur which you can use for writing AppleScripts. First we 
discuss the structure of our script, then we fill in the details. 

The structure 

Listing 3 shows the structure of our conversion script 
Convert to 3DMF. We use the on open construct so that we 
can use die script as a droplet. The file specifications of ihc 
files dropped onto the droplet appear in the list in Duelist. We 
traverse the list mDocList through a repeat command and act 
on each file in turn. First we do the most basic of error 
checking* Within a try statement we check whether the file is 
of type 'TEXT', If it is not* we bail out by throwing an error 
which leads to execution of the on error portion of the try' 
statement. If it is a lext file we call the parse handler. Within 
the parse handler we again have a try statement in which we 
Lrv to extract the relevant information front the raw 7 JD text 
file and format it according u> 3DMF standards. If all goes 
well we call ihe writeResultFile handler with as arguments the 
file specification of the raw 3D text File and the text of the 
3DMF file to write. Within the writeResultFile handler we try 
to create a text file within the same directory as the raw 3D 
texl file and the same name* except for ihe extension which 
we make 3df, Now that we have some idea of the structure 
of our script, let’s turn our attention to the parse handler* 

Listing 3: The structure of Convert to 3DMF 

m open CinBocList) 

— traverse the list *>f files that were dropped on the droplet 
repeal with theFUePath in inDqcList 

try 

tell applicat ion "Finder"* 

—minimiil error cheeking: 

—check whether ilie file is of type lext. 

—if it isn't* throw an error 

If (get file type of file theKltePftthJ^’TEXT* then 
error "This is not a text flic," 
end I f 

end tell 

—if we gel here the file type is "TEXT" 

—Lind wc parse the file 
parse(theFiiePath] 

on error inlrrorTexi 

—handle any errors that may occur. 

display dialog ("An error has occurred:" 

iriFrtorText) 

end try 
end repeat 
end open 

on parse(inFilcFath) 
try 

—Here we try lo read the raw 30 file, 

—extract the relevant Information. 


—and format it into 3DMF format, 

<code oroItied> 

—Cjail a handler to write the result to a file, 

writeResultFile(ifiFilePnth, rheDutputString) 

on error inErrorText 

display dialog ("An error has occurred:" A 
iitErrorTexi) 

end try 
end parse 

on writeResultFile (inFileFath, InOut put.Strlng) 
try 

—Here wc try to create a new text file 
—in ihc same director} as the raw 3D file, 

—only with the extension'frlf instead of ixf 
—and write our formatted result to it. 

<code omitted) 

on error inErrorText 

display dialog ("An error has occurred:" h iiiErrorText) 
end vriieResul tFile 


The Parse handler 

For the code of the parse handler please refer lo Listing 
4. First we read all of the raw 3D text file into a list called 
IheLmelist using returns as delimiters. This means that each 
element of the list tbeUneList contains one line of rhe raw 3D 
text file. Wc then traverse this list of lines using a repeat 
statement and look at the start of each line. There are 
number of possibilities 

II a line starts with "description" we arc dealing with the 
first line of the raw 3D text file which holds a description. 
Although this may seem superfluous as the file has a 
descriptive name, it can he a convenient location to store a 
long [>32 characters) description of the 3D object in the file. 
We ignore the word "description” and the colon and store the 
rest of the line in the string variable theDescriphon. 

If a line starts with "vertices" we have come across the 
line which signals the start of Lite vertices description and 
which tells us the number of vertices in the file. We simply 
ignore this line. Instead of grabbing the number of vertices 
from this line we w ill count the vertices as we encounter them. 

If a line Marts with "faces" we are dealing with the line 
which signals the start of the faces description and which 
tells us the number of faces in the file. Again we ignore this 
line as we will also count the faces as we encounter them. 

If a line starts with "vertex* we have a line with a vertex 
description* We ignore everything on this line up to and 
including the first comma which means that we eliminate the 
word “vertex" and the numlier of the vertex* The remainder of 
a vertex description line needs some filtering. We traverse this 
remainder looking at each character in turn. We replace the 
commas by spaces and eliminate superfluous spaces. For this 
last action we need to keep track of the last character using ihe 
variable theLaslChar. For example* if there is a space between a 
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minus sign and a comma we eliminate that space. Also, if there 
are multiple consecutive spaces we reduce them to a single 
space. The characters we wish to keep are appended to the 
variable IfteVerlicesSlring. After each line we add a comment 
with the index number of the vertex. By the time we have 
finished parsing all the vertices theVerticesString holds nice, 
clean versions of all the vertices in the file, 

If a line starts with “face" we are dealing with a face 
description. The filtering of a face description is pretty 
similar to that of a vertex description. Again we ignore 
everything on this line up to and including the first comma. 
This means that w'e have got rid of the word “face" and the 
number of vertices involved in the face, Unlike with a vertex 
line, we need not worry about decimal places. What we do 
need to do is count the number of vertices involved in a face. 
If a digit is preceded by a space or a comma we increment 
the variable IheNumberOtVerticesInFace. The characters wc 
wish to keep are appended to the variable theFacesString, 
After each line we add a comment with the index number of 
the face. By the time we have finished parsing the faces 
iheFacesString holds a nicely formatted version of all the 
faces in the file. 

If a line starts wit It "DiffuseGolor" we are dealing with 
the colour specification. We ignore the word “DiffuseColor* 
and the colon and store the rest of the line in the string 
variable theColor 

If a line does not conform to any of the previous 
options, then we either have an empty line or a line that we 
do not currently support. These lines are simply ignored. 

In its current form, the script does not cater for holes. 
The number of contours is simply set to 0. 

The rest of the parse handler assembles the various parts 
into a string variable theOutputStr, All we need to dn now is 
write our freshly formatted string theOutputStr to a file 
through the handler writeResultRle, 

Lis ling 4: Parsing and formatting 

parse 

on parse (inFilePath) 

—initialise the number of vertices 

set theNutnOfVerrs to 0 

—initialise the number of faces 

set theNumOfFace^ to 0 

■“the string with vertex descriptions 

set theVertsStr to MH 

—tile string with lace descriptions 

set theFacesStr to "" 

try 

—Copy the content of the text File into a list. 

—Use return as tile delimiter. 

—This makes each list element one line. 

copy (read inFilePath as list using delimiter return) - * 
to theLineList 

— Traverse the list of lines 


repeat with i from ** 

1 to the number of Items in theLineList 

set theLine to item i of thdLineLiat 

if theLine contains “Description* 4 then 
—Skip the label "description" and copy the rest, 
set theDescription to characters ”■ 

((the offset of ":" in theLine) + 1) 

thru (the end of theLine) of theLine as string 

else if theLine contains “Vertices** then 
—Signals the start of the vertices Hat: do nothing 

else if theLine contains "Faces** then 

—Signals the start of the faces list do nothing. 

else if theLine contains “Vertex" then 
—This is a vertex description 

—Track the last character we read. 

Set theLastChar to "** 

“Tmver.se the line from the comma to the end of the line 
repeat with j from ((the offset of in ■* 

theLine) f 1} to the number of characters -5 
in theLine 

copy character j of theLine to theChar 

if "1234567890'." contains theChar then 
—These are valid characters which wc keep 
set theVertsStr to theVertsStr 6 theChar 
else if theChar w then 
—Wc replace commas by spares 
set theVertsStr to theVertsStr & " 44 
else if theChar " H " then 
if theLastChar = **" then 

—Line starts with a space : don’t copy the space 
else if theLastChar = then 

—spare preceded by a minus sign don’t copy the space 
else if theLastChar * " " then 
—IWo consecutive spaces: don't copy the “ * 
else if theLastChar “ ***** then 

—space preceded by a comma: don't copy the spare 
else 

—This is a space wc wish to keep 
set theVertsStr to theVertsStr & " " 
end if 

end if 

— Keep track of the last character 

copy theChar to theLastChar 
end repeat 

— We append a comment with the vertex number to this line. 

set theVertsStr to theVertsStr & ~" 1 
" 41 6 & theNmnOfVerts 6 return 

—increment the number of vertices we have dealt with. 

set theNumOfVerts to iheNumOf 1 Verts t I 


else if theLine contains "Face" then 

—This is a face description. 

set theCurrFaceStf to "** 
set theLastChar to M t *‘ 
set theNunOfVertsInFace ro 0 

—Skip everything upiu and including the first comma. 

—Traverse the line from the comma to the end of the line 

repeat with j from ((the offset of In “* 
theLine) +1) to "* 
the number of characters in theLine 

copy character j of theLine to theChar 

if “1234567890" contains theChar then 
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—These are valid characters which we keep 
copy theCurrFaeeStr b theChar to -> 
theCurrFaceStr 

—If this valid character is preceded by a comma or a space, 
—then it must he a new vertex number. 

if theLastChar = "or theLastChar ® “ M then 
copy theNumOfVertsInFace + 1 to ^ 
theNimOFVe rts I nFac e 
end if 

else if theChar - "," then 
—We replace commas by spaces 
set theCurrFaceStr to theCurrFaceStr & “ “ 

else if theChar “ M " then 

if theLastChar = “ w then 

— Line starts with a space: don't copy the space 
else if theLastChar ■ *'■" then 

—" H proceeded by a minus sign: don't copy the space 
else if theLastChar = “ " then 
—Two consecutive space s; don’t copy the “ “ 
else if theLastChar = then 

—space preceded by a comma: don't copy the space 
else 

—This is a space we wish to keep, 
set thftCurrFaceStr to theCurrFaceStr & " ** 
end if 

end if 

—Keep track of the last character 
set theLastChar to theChar 

end repeat 

—Build a line with a face description, 
set theCurrFaceStr to LheNui&QfVertsInFace & 1 
" k theCurrFaceStr k ~ " k b theNumQfFaces 

—Build the description of all the faces, 
set theFacesStr to theFacesStr h ”> 
theCurrFaceStr & return 

—Increment the number of faces, 

set theNumOfFaces to theNurnGfFaces + 1 

else if (item i of theLineList) “* 
contains "DiffuseColor" then 

set theColor to characters ^ 

((the offset of in theLine) + 1) "» 

thru (the end of theLine) of theLine as string 

else 

—Probably an empty line or something unsupported, 

end if 
end repeat 

—There arc no holes in our model so the number of contours is 0. 
set theNumOfContours to 0 

-The 3I>MF header, 

set theHeader to "3DKeLafile{1 6 Normal toe))" Gt return 
—The description 

set LheDescrlption to "|L' b theBescription A return 
—The attribute set 

set theAttributeSet to "AttributeSet ( )** & return & 
"DiffuseColor (" b theColor & k " #r g b" ^ 
return 

—We've got the parts, now assemble the 3DMF ftie 
—in the string variable theOutpuiStr, 
net LheOutputStr to *» 

Lheileader & 
theUescription & _1 

"Container (“ b return b “Mesh(“ b return & 


theNuraOfVerts b “ iftium of vertices” k return k 
theVertsStt b ^ 

theNumCFFaces b M Ij-tmm of faces" k return & 
theHumOfContours b * $n\m of contours" k return b 
theFacesStr & 

14 )" b return k - 
"Container {" & return b 
theAttributeSet b “» 

*')" k return b 
“) rt 

—Call a handler to write the result to a flic. 

writeResultFlle(inFilePath. theOutputStr) 

—Bond 

beep 

on error InErrorText 

display dialog ("An error has occurred: " k 
inErrorText) 

end try 
end parse 


The writcRcsultFHe Handler 

Now thal wc have the siring theOutputStr all that remains 
to do is ro write it to a text file. This happens in the handler 
writeResullFile (Listing 5L In the inFilePath parameter we pass 
the handler the file path of the raw 30 text file. We want to 
create a finished 3DMF in the same directory and with the 
same name as the raw 3D text file but with a different file 
extension, which we want to he .3df. If the raw text file has 
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the file extension .txt we chop i[ off first. Using the newly 
created file path theOutfilePathStr we open a file with write 
permission. We then write our string inOutputStr to this file 
and sec its type and creator. The type is 3DMF and here we 
use SimpleText as the creator though of course you can 
change the creator to the application of your choice* Finally t 
we close the file* 


Listing 5: Writing our result to a file 

on writeResuIttfIle(inFileFath , itiOutpulSLr) 


w rite Res til iFik 


—Cast ihc tic path to a siring. 

copy 1nF1lePath as string to theFilePatbStr 

—wc write rite resulting 3DMF file to the same directory as our original text file. 
— it the file path ends with .txt cut off the txt 

if (theFilePathStr) ends with "*txt w then 
set theOutfilePathStr to (characters 1 thru 

((the offset Of in theFilePathSir) 1) -* 

of theFilePathStr) as string 

else 

sot LheOuifilePathStr to thePilePathStr 
end if 


called table.3df appears in the same directory as table,txt* 
Double dick the file. SimpleText should open and the 
QuickDraw 3D Viewer should display our table as shown in 
Figure 2* Tf you are unsure how to use the controls of the 
QuickDraw 3D Viewer, check out Balloon Help as it is quite 
helpful* On some systems the file may not open correctly 
after a double dick in die Finder and shows as a QuickTime 
movie instead. This can be solved by launching SimpleText 
and choosing table.Sdf from the File Open dialog box. As this 
is of course awkward if you would like to open multiple 
files, Listing 6 shows a small script for a droplet which 
correctly opens 3DMK files that are dropped onto it . Note 
that if you use a non-English language system, AppleScript 
may ask you to locate your localized copy of SimpleTexL 
which is hiding on your harddisk under a different name. 

Listing 6; Open3DMF 

on open (InDooLIst) 

repeat witli IbeFileSpee In inDocList 


—Append 3df to ilic fiic path in case of use by the evil empire', 

set theOutfilePathStr to theOutfilePathStr U 

—Create a file to write our result to 

copy (open for access file theOutfilePathStr "* 
with write permission) to theOatFileRef 


fell application “Simp 1eText M 
open theFiieSpsc 
activate 
end tell 

end repeat 


try 


end open 


—Write the output string to the file, 
write inOutputSir to theOutFileRef 

—Set ty pe and creator 

tell application "Finder* 

—Set the type to jVDMF, the file type of a 3D Metafile 

set file type of file theOutfilePathStr to "lOMF" 

—Wc want the file to be openablc by SimpleText (creator 
—But of course others are possible 
—FormZ (creator *VTVS") 

—CicoiT) (creator *3TC*) 

—3DMFOprimizer (creator "OP20") 

set creator type of file theOutfilePathStr to “ttxt" 
end tell 

—Close the result file 

close access theOutFiieRef 

on error InErrorText 
—Close the result file 

close access theOutFileRef 

display dialog ("An error has occurred: 

& LnEirorText) 

end try 

end writeResultFile 


Finishing and trying out our script 

We finish our script by turning it into a droplet. Choose 
save as from Script Maker's file menu, enter the name Convert 
to 3DMF and choose classic applet from the structure popup 
menu. Now drop the raw 3D text file table txt on the Convert 
to 3DMF droplet. After a brief pause the Mac beeps and a file 


Discussion 

In this article we showed you how you c an get your data 
into QuickDraw 3D ? s 3D Metafile format. We barely 
scratched the surface but now that you are up and walking 
you can teach yourself how to run using the following 
pointers. 

Quesa: QuickDraw 3D to the future? 

Quesa (www.quesa.org) is the astounding open source 
effort to build a 3D graphics library which offers binary and 
source level compatibility with QuickDraw 3D. If you are 
hesitant to support QuickDraw 3D because of Apple's 
announcement to drop the technology, you may wish to 
investigate Quesa. Quesa is not only suitable for Mac OS8/9 
and MacOSX, it is completely cross-platform with support for 
Windows and Linux. A port for Be is expected. 

Learning more about 3DIVIF 

You can find a well organised collection of links to 
QuickDraw 3D documentation, including the 3D Metafile 1*5 
Reference documentation, at www,quesa,org/other/links.html. A 
good read on a rainy Sunday afternoon, the 3D Metafile 
documentation tells you in approximately 250 pages 
everything there is to know about 3DMF. You should pay 
special attention to these two aspects of the 3D Metafile: 

* Alternative geometry types 

For our file wc have used QuickDraw 3D's mesh 
geometry. The advantage of the mesh is that it is easy to 
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understand and write and that there are many QuickDraw 
3D calls for mesh editing, Jls trig disadvantage is that it is 
rather inefficient when it comes to rendering. If you are 
mainly interested in fast rendering you may wish to look 
into two other geometry types: the polyhedron and the 
trimesh. 

AnoLhcr option is to use 3DMF Optimizer by Pangea 
Software to convert your meshes into trimeshes 
(www.pangeasoft.net/downloads.html), 

* Binary vs, ASCII 

So far we have been writing 3DMF ASCII files. There is 
also a binary 3DMF format. The binary format results in 
smaller files which can be read faster by QuickDraw 3D 
applications. Luckily, there are conversion utilities 
around which convert our 3DMF ASCII file to a 3DMF 
binary file. One such utility is Armas by Stefan Huber 
(www.topoich). It converts from ASCII 3DMF to binary 
3DMF and vice versa. 

Better tools for AppleScript 

While ScriptMaker is a great freebie and quite adequate 
for writing small AppleScripts, you will start to notice its 
limitations as your scripts start to grow. There is no built-in 
search and replace, variable watching or step-by-step 
debugging. If you feel you need a better AppleScript 
development environment have a look around at Developer 
Depot (www.devdepot.com). There you will find some 
professional AppleScript tools. 

Better 3D tools 

As the name implies the QuickDraw 3D Viewer is limited to 
viewing 3DMFs. It does not allow you to edit them, A far more 
capable freeware application is Geo5D by Stefan Huber which is 
a better viewer and adds some editing and animation features 
(www.topoi.dl). If you need a full-blown modelling, rendering and 
animation freeware package you may wish to consider Straia3D 
(www.strata,com/html/demos_updates.htnnl). This is a stripped down 
version of what used to Lie Strata StudioPro. Finally, most 
commercial 3D applications edit 3DMFs, 

Conclusion 

This article showed you how to use AppleScript to take 
a raw 3D text file and convert it into the 3DMF file format, 
viewable by any QuickDraw 3D application. Pari of the fun 
was rhar the technologies and applications that we used — 
QuickDraw 3D t the QuickDraw 3D Viewer, AppleScript and 
ScriptMaker — all come standard with your PowerMacintosh. 
You can of course push the boundaries further by trying to 
export 3D daLa from your favourite commercial database or 
spreadsheet application. Enjoy! HQ 
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QUICKTIME 

TOOLKIT 


By Tim Monroe 


The Atomic Cafe 


Working With Atoms and 
Atom Containers 


Introduction 

In the past two QuickTime Toolkit 
articles, we've been concerned at least in 
part with atoms, the basic building-blocks 
of QuickTime movie files. Atoms are 
utterly simple in structure (a Tbyte length 
field, followed by a 4-byte type field, 
followed by some data), and this utter 
simplicity means that atoms can be used 
for a very wide range of tasks, Indeed, the 
atom-based structure used by Quicklime 
movie files is so general and so flexible 
that it has been adopted by the 
International Standards Organization 
(ISO) as the basis for the development of 
a unified digital media storage format for 
the emerging MPEG-4 specification. 

In this article, we’re going to continue 
investigating the basic structure of 
QuickTime files as sequences of atoms. 
You might recall that tn the previous article 
we left some unfinished business lying 
around, Namely, we need to .see how to 
replace an existing atom of a particular 
type instead of just adding a new atom of 
that type. It turns out that handling this task 
in the general case is reasonably difficult, 
since we can’t safely move the movie data 
atom around in a movie file without doing 
a lot of work. For the present, we’ll be 
content to see how to amend the 
GTlnfo_MakeFilePreview function we 
developed last time so that there is at most 
one + pnot f atom in a QuickTime movie file. 


Because an atom can contain any kind of data 
whatsoever, it can contain data ihat consists of one or more 
other atoms. So, atoms can be arranged hierarchically. Well 
take a few moments to consider the hierarchical arrangement 
of a movie atom (the main repository of bookkeeping 
information in a QuickTime movie file). Then well show 
how to put our atom-fusing powers to work to create a 
shortcut movie file, a QuickTime movie File that does nothing 
more than point to some other QuickTime movie file. 

Once we've played with atoms for a while, we’re going to 
shift gears rather abruptly to consider a second kind of atom- 
based structure, which well call an atom container. Atom 
containers are structures of type GTAtomContainer that are often 
UsSed inside of QuickTime movie data atoms to store various 
kinds of information (for example, media samples). They were 
developed primarily to address some of the shortcomings of 
atoms. In particular, the Movie Toolbox provides an extensive 
API for working with atom containers; among other things, this 
API makes it easy Lo create and access da La arranged 
hierarchically within atom containers. 

Well get some hands-on experience with atom containers 
in two ways. First, well see how Lo get and set the user's 
Internet connection speed preference, which is a piece of 
information that QuickTime stores internally and happily gives, 
m the form of an atom container, Lo anyone who asks. Second, 
well see how to add a movie track to a QuickTime movie. By 
using movie tracks, we can embed entire QuickTime movies 
inside of other QuickTime movies The movie media handler ; 
which manages movie tracks, is one of the most exciting new 
features of QuickTime 4,1, Once we understand how to work 
with atom containers, it'll be easy lo add movie tracks to an 
existing QuickTime movie. 

Before we begin, though, a word about terminology. As 
you’ve been warned, this article is going to discuss two different 
ways of organizing data, lx>th of which are (for better or worse) 
called "atoms". The first kind of atom is the one that's used to 
define the basic structure of QuickTime movie files. The second 
kind of atom is the one that was introduced in QuickTime 2.1 


Tim Monroe recently acquired 3 pet lizards (green anoles), not realizing that he’d need to feed diem things like crickets, 
mealworms, and spiders. His house Is now surprisingly spider-free, however. You can send your bugs to him at 
monroe® apple, com. 
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for storing daUi in some kinds of media samples (and for other 
tasks as well); these kinds of atoms are structures of type 
QTAtom that are stored inside of an atom container. 

Some of Apple's QuickTime documentation refers to the 
first kind of atom as a classic atom (perhaps in the same spirit 
that one refers to a classic car: it's been around a while) and 
to the second kind of atom as a QT atom (drawing of course 
on the data type QTAtom). Some other documentation refers Lo 
the first kind of atom as a chunk atom (perhaps because it’s 
just a chunk of data?). I'm not particularly happy with any of 
these terms, so Fm going to refer to the first kind of atom 
simply as an atom and to the second kind as an atom 
container atom. In other words, an atom container atom (of 
type QTAtom) is always found inside of an atom container (of 
type GTAtomContainer). Generally, here and in the future, the 
context will make it clear which kind of atom we’re 
considering, so we can usually get by just talking about atoms. 

File Previews: The Sequel 

in the previous article (“The Informant* in MacTecb, 
July 2000), we sa^y how to add a ‘pnot r atom to a QuickTime 
movie file, to create a single-fork movie file with a file 
preview. (A file preview is the movie dip, image, text, or 
other data that appears in the preview pane of the file¬ 
opening dialog box displayed by a call to 
SiandardGetFSIePreview or NavGetFile.) Our strategy was 
simple: each time the user saves a movie, add a preview 
atom and (if necessary) a preview data atom to the 
QuickTime movie file. But we recognized that ultimately we 
would need to refine this strategy to avoid ending up with 
multiple preview atoms and preview data atoms. It's time to 
make some changes to our QTFnfo application, in this 
section, we’ll see how to upgrade QTlnfo into a nearly - 
identical application, called QTlnfoPlus, that handles file 
preview atoms correctly. 

Removing Existing Previews 

In fact, we can solve this little problem by adding a 
single line of code to the QT1nfo_MakeFilePreview function. 
Immediately after determining that the file reference number 
passed to QTlnfoJVlakeRlePreview picks our a data file, we 
can execute this code: 

QTlnfo ReuioveAllPrevievsFtomFile(iheRefNum); 

The QTInfo_RemoveAIIPreviewsFromFile function looks 
through the specified open data file and removes any 
existing preview atoms (that is, atoms of type ‘pnot’) from 
that file. In addition, this function removes any preview data 
atoms referenced by those preview atoms, unless the 
preview data atoms are of type 'moov. (We don't want to 
remove atoms of type l moov’( of course, since they contain 
essential information about the movie file.) 
GTInfoJFemoveAlfFreviewsFromFile is defined in Listing 1. 


Listing 1: Removing all preview atoms from a QuickTime 
movie file 

QTl n ft j_Re m oveA 11P rev lew sFromFi le 

QSTvrr QTTnfo_RemovE?A11 PreviewsFromFile Cohort thaRefNum) 

I 

long myAtomType = 0L: 

short myAtomlndex - 0: 

short myCount - 0: 

OSErr myErr = noErr; 

// count the preview atoms in the file 

my Count = QT I n f cl_C o u n t A L omsO f Ty pel riFil e (t he Re fNum, OL* 

SI i owFi1e P r&viewComp on&nt Type)I 

while (myCount > 0) [ 

// get the preview data atom targeted by this preview atom 
myAtoiaType - ShowFileFreviewComponentType; 
myAtomlndex = myCount; 

myErr = QTlnfo FindPreviewAtomTarget(tbeRefNum, 

fiimyAtomType. imyAtorriIndex); 

// if the preview data atom is the last atom in the file, remove it 
if (unless it's a mioov’ atom) 
if (myErr = noErr) 

If (JnyAtomType != Ho vie AID) 

if (QTInfo_IsLastAtomInEile(theRefNum. 

rayAtoroTyps , myAtom I ndex}) 
QTlnfo RemoveAtomFromFile(theRefNum, 

rayAtornTypn, myAromTndox); 

ft remove or free the preview atom 

if (QTInfo_isLftstAtomlnFile(tbeKefUmm. 

ShowFiiePreviewComponentType, myCount)) 
QTInf o_Remove At omFromF lie {t heRef JJum * 

ShowFilePreviewComponentType. myCount); 

else 

QTInfo_FreeAtomInFile(theRefMunj, 

ShowFilePrev iewCotnponontTypo, my Co uni); 
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// it the preview dam atom Mill exists, remove or fire it (unless it's a'moov' atom) 
if (myErr = noErr) 

if (rcyAtomType 1= MovieAID) 

if (QTlnfo^IfiLaEtAtoinlnFile(theRefNiun, 

my At.omTy pe * myAtorn T nd ex)) 
QTiJi£o_RemuveAtoi^roiuFile (theRefMum. 

myAiomi'ype P myAtomlndex) i 

else 

QTInfo_FreeAtomlnFiis [theRelNum , 

myAtomType P iriyAtomlndex) ; 

my Count—: 

\ 

return[myErr); 

) 

As you can see, QT1nto_RemoveAIIPreviewsFromFile calls a 
handful of other functions defined by our application, 'these 
other functions do things like count ihe number of existing 
preview atoms, find the preview data atom that is the target of 
a preview atom, determine whether a given atom is the last 
alom in the file, and so forth, 

QTInfo_RemoveAIIPreviewsFromFile puts these functions to 
work like this: for each preview atom in the file (starting with 
ihe one nearest the end of the file), find the preview data 
atom that is referenced by the preview atom. If that target 
atom isn'L a movie atom and it's the last atom in the hie, 
remove it from the file. Then, if the preview atom is the last 
atom in the file, remove it as well. If the preview atom isn’t 
the last atom in the file, then change it into a free atom (that 
is, an atom whose type is FreeAtomType), By changing the 
atom type, we’re converting the preview atom mLo a block 
of unused space at its current location in the movie file. 
QuickTime simply ignores any atoms of type FreeAtomType 
that it encounters when reading through a movie file. 

You might think that we could just remove a preview 
atom from the file and, if it isn’t the last atom in the file, 
move any following atoms up in the file. This would avoid 
creating “islands" of unused space in our file, hut it would 
be a dangerous thing to do. That’s because some atoms in a 
QuickTime file reference data in other atoms by storing 
offsets from the beginning of the file. In general, we want to 
avoid moving atoms around in a QuickTime movie file. It’s 
safer just to convert any unwanted atoms that are not at the 
end of the file into free atoms. 

Once we've removed a preview atom (if it's the last 
atom in the file) or converted it into a free atom (if it isn’t)* 
we then look once again to see if the preview data atom is 
the last item in the file, flits might happen if the preview 
data atom originally preceded the preview atom and the 
preview atom was the last atom in the file. If the preview 
data atom is now the last atom in the file, it’s removed; 
otherwise* it’s converted into a free atom. 

The net result of all this is to remove any existing preview 
and preview data atoms from the file, either by truncating the 
file to exclude those atoms or by converting them into free 
atoms. At this point, QTInfo_MakeFilePreview can safely add a 
new preview atom and (if necessary) a preview data atom to 
that file. So, when all is said and clone, the Quicklime movie 


file will end up with exactly one preview atom and one preview 
data atom. In the next few subsections* well consider how to 
define the various QTInfoFlus functions called by 
QTInfo^RemoveANPreviewsFromFile. 

Finding and Counting Atoms 

The most fundamental thing we need to be able to do, 
when working with a file that’s composed of atoms, is find an 
atom of a specific type and index in that file. For instance, we 
might need to find the first movie atom, or the tim'd preview 
atom, or the third ’PtCT atom in the file. So w r e want to devise 
a function that Lakes an atom type and an index and then 
returns to us die position in the file at which that atom begins, 
if there is an atom of that type and index in the file, Otherwise, 
the function should return some error. 

This task is reasonably straightforward. All we need to 
do is start at the beginning of the file (or at some other 
offset in the file specified by the caller) and inspeci ihe type 
of the atom at that location. If the desired index is 1 and the 
desired atom type is the type of that atom* we Ye done: 
we’ve found ihe desired atom. Otherwise, we need to keep 
looking. We can find the next atom in the file by moving 
forward in the file by the size of the atom currently under 
consideration. We continue inspecting each atom and 
moving forward in the file until we find the atom of the 
specified type and index or until we reach the end of the 
file. Listing 2 defines the function 
QTInfo_FjndAtqmOfTypeAndlndexlnFile, which is our basic 
atom-finding tool. 

Listing 2: Finding an atom in a QuickTime movie file 

(ynnfo_FindAromOnypeAnd]ndexf nHi le 

OSErr QTlnfoJ'indAtomOfTypeAndiridexlnt'ile {short theRefNum* 
long ‘theOffset, long theAtomType, short thelndex, 
long ‘theDataSize, Ptr *theDataPtr) 

( 

short rayIndex = 1; 

long myFileSize: 

tong myFilePos = OL; 

1 m\g rayAlomHeade r [2] ; 

long mySize * OL; 

CJSTypt? myType - OL; 

Ptr rayDataPtr = NULL: 

Boolean isAtomFound = false: 

OSErr myErr = pararaErr: 

if (theOffsFt = NULL) 
goto halt; 

if {QTlnfo^sRefNuinOfResourcBt’ock (theKefNmn)) 
goto bail; 

myFilePos - *theOffset; 

// got the total size of the file 

GetEOF(theRefNum. kmyFileSize); 

while (I isALomFouiid) { 

EnyErr 11 SetEPos(theRefNum, fsPromStart, myFilePos): 
if (myErr 1= ooErr) 
goto bail; 

// rod tilt atom htrader Jt the current file position 

mySize = slzeof (myAtoniHeader); 

myErr = FSReadithelefNura, &my5ize. myAtoraHeader): 
if (myErr !“ noErr) 
goto bail: 
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mySize ” EndlanlJ32_tUoN(oiyAtomHeader [0]) : 
mytypo ** EndIanU3Z_Btt>N(myAloinIleadGr [l] ) ; 

if ((myIndex — thelndex) && 

((theAtomType *— rayType) 

| (theAtoaType “ kQTInfoAnyAtomType))) I 
// wc ftmnd an mom of the specified type and index; 

// return the atom if the calter wants it 
if (theDataPtr NULL) l 

myftarsPrr “ NewPTcClear(mySizp): 

If (ayDataPir = NULL) I 
atyErr * MemKrrorO; 
goto bail; 

I 

// hack up to the beginning of the atom 

myErr = SetFPoa(theRefNum, fBFromStart, rnyFilePos): 
if (myErr 1“ noErr) 
goto ball; 

myErr = FSRoad(theReftfum, SmySize, myDataPtr); 
if (myErr \~- noErr) 
goto bail; 

i 

isAtonFmmd * true; 

I else I 

// we haven’t found an atom of the specified type and index; keep on looking 

myFilePos += mySize; 

if ((theAtomType — myType} | 

(theAtomType “ kQTInfoAnyAtomType)) 

myIndex++ : 

// make sure we re moving forward in the file, hut not too far 

If ((mySize <” 0) fj 

(layFilePos > (myFileSize - sizenf (nryAtomHeader)))) ( 
myErr ** CcmnotFindAtomErr; 
goto bail; 
l 
I 

I // wtiik (EisAtomFuimd) 

// if we got to here, we found the correct atom 

if (theOffeul !- NULL) 

•tbeOffset “ myFlleFos; 

if (theDataPtr !- NULL) 

‘theDataPtr * myDataPtr; 

if (theDataSize I* NULL) 

‘theDsta&ize " mySIxe; 

bail: 

if (myErr !" noErr) 
if (myDataPtr 1= NULL) 

DisposeFtr(myDataPtr); 

return(myErr): 

) 


QTInfo_RndAtomOfTypeAndlndexlnRle returns to its caller 
die offset within the file of the beginning of the atom of the 
desired type and index. In addition, if the caller passes in non- 
NULL values in the theDataPtr or theDataSize parameters, 
QTInto_FindAtomOfTypeAndlndexlnRle returns a copy of the 
entire atom (including the atom header) or die atom size to the 
caller. Ihe returned offset, data, and atom size can be used for 
a variety of purposes* For instance, listing 3 defines the 
QTInfo_CountAtomsOfTypelnFiie function, which counts the 
number of atoms of a specific type in a file. 


lasting 3= Counting the atoms in a QuickTime movie fil e 

QTInfo CourtLAlomsOflV'pelnPik 

short QTInfo_CountAtomsOfTypeInFIle (short theRsfNum, 

long rheOffset, Tong theALoniType) 

I 

short myTndex ** 0; 

long myFilePos = tbeOffset; 

long myA Lulu Size " 0L: 

OSErr myErr “ noErr; 

if (QTInfo^IaRefNumQfReaourceForMtheRefNum)) 
return(myIndex); 

while (myErr = noErr) I 

myErr = (JTInfo_FlndAtomOfTypeAndIridexInFile (theRefNum, 

SrrayFlIePos, theAtoiuType, 1, kmyAtainSize > NULL); 
if (myErr — noErr) 
raylndex++; 

myFileFos += myAtomSize; 

// avoid an infinite loop,,. 

if (myAtomSize 0) 
break; 
l 

teturn(mylndex): 

1 

QTlnfo_CountAlomsOfTypetnRle uses the offset and atom size 
returned by QTInfo_FindAtomOfTypeAndlndexlnFile to walk 
through the fide looking for atoms of the specified type. 

Similarly, it’s easy to use QTInfo_F!ndAtomOffypeAndlndexlnFite 
to determine whether a particular atom is the last atom in a file. 
We simply call QTInfo_FindAtomOfTypeAndlndexlnFile to get the 
offset in the file of the given atom and then call it again to see if" 
there are any atoms of any kind following that atom. Listing 4 
defines a function that does precisely this. 

Listing 4: Determining w hether an atom is the 
last atom in a file 

QnnfbJsLastAtomTnFIk 

Boolean QTInfo JlaLaatAtoralnFlie (abort tboRofNum, 

long theAtomType, short theIndex) 

Boolean isLasiAton * false: 

long myOffset = 0L; 

long myAtornSize * 0L; 

OSErr myErr ** noErr: 

// find tilt otfsci and size of the atom of the specified type and into inthe file 
myErr = QTInfo .FlndAtomOfTypeAndlndexTriFileftheRefNum, 

&myOffset, theAtomType, thelndex, AmyAtomSize* NULL); 
if (myErr ™ noErr) I 
// look for an atom of any ty r pc following that atom 
myOffset ttyAtomSize; 

myErr = QTInfo_FlndAt omOfTypeAnd Index InFl le (theRefNum* 

& my0 ffeet. kQTl n foAnyAt omType, 1, NULL, NULL); 

If (myErr 1-* noErr) 
isLastAtom “ true; 

I 

return(IsLastAton): 

1 


Finding the Preview Data Atom 

Given a preview atom, we sometimes need to know which 
other atom is Ore target of tliat atom. In oilier words, we want to 
find the atom that weVe been calling the preview data atom — the 
atom that contains the data for the file preview, 'lhis is fairly easy; 
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we just need to read the data in the preview atom, which lias the 
structure of a PreviewResourceRecord record. listing 5 defines the 
QTI nfo^F ind P re view Atom Target function, which docs tills. 


Listing 5i Finding the target of a preview atom 

QTl n fo_Fmd Pit view Atom I angel 

GSEr* Ofrinlp^FindPreviewAtomTarget (short theRelNum. 

long •theAtomType, short 'theludex) 

( 

long myOffset = QL; 

PreviewResourceRecord myPNOTRecord; 
long mySize: 

OSErr myErr “ noErr; 

if ((theAlomType — NULL) || (thelndex — HULL)) 
return(paramErr): 

// find lilt ottm of the atom of ihc specified type and index in the file 
myErr m QTInfo_FindAtomOfTypeAndIrtdexInFile(theRefNuni, 

AmyOffset. 'theAtorolype, •thelndex. NULL. NULL): 
if (myErr — noErr) l 

// sen the file mark to the beginning of the atom data 
myErr " SclFPos( theRefNiJiii„ fsl'romStart* 

rayOffeet + (2 * siZGQt [long))): 

if [myErr — noErr) \ 

// read tlic atom data 

mySize * sizeof(nyFNOTRecord) : 

myErr * FSRead (theRefNuiri. AmySize, kmyPNOTR^tord); 
if (myErr = noErr) I 

* theAtonsTypc ” End ianU32_RloN (ray PNOTRecor d . resType ] : 
■thelndex = EndianS16_fltoN(myPNOTRecord.resID): 

1 

l 

J 

return(myErr ); 

I 


QT I nfo_Find Pre viewAtom Target oils 
QT! nf o_Fi nd AtomOfTypeAnd I ndex f nFile to find the location of the 
atom whose type and index are passed to it in tiie theAlomType and 
thelndex parameters- Then it advances the file mark to the 
loginning of the atom data and reads the atom data into 
myPNGTRecord, The type and index of the preview data atom 
(suitably converted from big-endian to native-endian form) are then 
returned to the caller 


Removing and Freeing Atoms 

[is quite easy to remove an atom from a file or convert it into 
a free atom. Listing 6 shows how we define the 
QTlnfo^RemoveAtomFromPile function, which removes an atom from 
a file by truncating the tile at the beginning of the atom (by calling 
SetEOF). Note that any atoms that follow the specified atom are also 
removed from the file. To avoid any problems, we should always 
call GTInfoJsLastAtomlnRIe to make sure that the atom to lie 
removed from die file is tiie last amm in the file. 


listing 6; Removing an atom from a file _ 

QTInfo_RcniovcAii>ml J rornFile 

OSErr QTTnfoJtemaveAtoiEFrQniFile (short theRefNum, 

long theAtomType, short thelndex) 

( 

long myOffset - 01: 

long myAtomSize * 0L; 

OSErr myErr " noErr: 

// find the offset of the atom of the specified type and index in the file 

myErr - QTInfo_FindAtoixOlTypeAndIndexInFile [theRetNum. 

&myGffset. theAtomType. thelndex, fonyAtomSize, NULL); 


if (myErr — noErr) 

myErr = SetEOF( theReftium, myOffsot); 

return(myErr): 


It's almost as easy to convert an atom into a free atom. All 
we need to do is position the file mark to the beginning of the 
type field in the atom header anti write the value free 1 into that 
field. Listing 7 shows how wc do this. 

Listing ?: Freeing an atom in a file 

QTinfo _ I ■ nrcAlomln Hie 

OSErr QTIn£o_i'reeAtomlnEile (short theRefNum, 

long theAtomType, short thelndex) 

I 

OSType myType = Endlanin2..NtoB[FreeAioqiType) : 

long mySize ~ sizeof(myType): 

long HryOffKet • r 0L; 

OSErr siyErr “ noErr; 

// find the offset of ilit atom of the sjicdlied type and index in the Ilk 

myErr = GTInfo_FindAtgiB0tTypeAndIndexIiiFile(theRefNuflt. 

tayOffset, theAtomType. thelndex, NULL . Mill .T.J: 
if (myErr — noErr) I 
// dungc die atom type to Tree" 
myErr =* SetFPos(theRefNiim t fsFromSiaru 

myGffset + eizeof(long)); 

if (myErr = noErr) 

myErr = ESWrite(theRetNum, intySize. &myType): 

i 

return(myErr); 

1 
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So far, then T weVe managed to define a handful of 
utility functions that allow us to find atoms in files, get the 
sizes of those atoms, remove atoms from files, count the 
number of atoms of a specific type in a file, and so forth. 
These are precisely the functions called by the 
QTInfo_RennoveAliPreviewsFromFile function, which we’re 
using to make sure that any QuickTime movie file we create 
or edit has at most one preview resource. It would be easy 
(and fun) to define an entire library of atom utilities, but 
well have to restrain our programming urges here. We've 
got other work to do. 

Shortcut Movie Files 

I mentioned earlier that an atom can contain any kind of 
data, and in particular it can contain other atoms. That is to say, 
atoms can be arranged hierarchically. Up to now, however, 
we’ve worked with a QuickTime movie file as a mere 
concatenation of atoms, We r ve looked at the data of several of 
those atoms, hut we haven't yet met any atoms that contain 
other atoms. It’s Lime for that to change. 

A g*xxl example of an atom that contains other atoms is the 
movie atom itself. A typical movie atom contains a track atom (of 
type TrackAlD) for each track in the QuickTime movie, along with 
other atoms liiaL contain the movie metadata. A movie atom can 
also contain a movie user data atom (of type UserDataAID), which 
contains the movie user data. A truck atom, in turn, contains other 
atoms i hat define the track characteristics and that point to the 
media data. And so on, as deep as is necessary to completely 
characterize a movie and its data. 

An atom that contains no other atoms is called a leaf 
atom , A leaf atom may or may not actually contain any data. 
Typically a leaf atom does contain data, but it's possible that 
the very presence in the file of the atom has significance, in 
that case, the leaf atom consists solely of the 8-byte atom 
header, An atom that contains one or more other atoms is 
called a container atom, A movie atom is a container atom. 
By contrast, a preview atom is a leaf atom, since it contains 
data but no other atoms. (A preview atom points to or 
references another atom, but it does not contain it.) 

Let’s build a container atom. Now, it's lieyond our current 
capabilities to build a typical movie atom, with all its 
complicated suhaloms and subsubatoms, But there is a kind of 
QuickTime movie file that consists entirely of a movie atom and 
which is simple enough for us to build; tills kind of file is called 
a shortcut movie file. A shortcut movie file is a movie file that 
picks out a single other movie file. It's rather like an alias file in 
the Macintosh file system or a shortcut on Windows, Opening a 
shortcut movie file using the Movie Toolbox function 
OpenMovieFiJe causes QuickTime to look for the file that is 
referred to by the shortcut movie file; if that target file can be 
found, then OpenMovieFiJe opens it and returns to the caller a 
file reference numlier for that target file. 

Shortcut movie files provide a cross-platform 
mechanism for referring to QuickTime movie files. They can 


be useful in all the same ways that alias files (on Mac) or 
shortcuts (on Windows) can be useful, at least when 
working with QuickTime movies. For instance, a web page 
might contain an embedded URL to a shortcut movie file, If 
the webmaster wants to update die movie displayed in Lhe 
web page, he or she needs only to create a new shortcut 
movie file that refers to the updated movie and then put the 
new shortcut movie file in the location occupied by the 
previous shortcut movie file. In this way, the contents of the 
web page can be changed without altering the actual HTML 
tags of the page. 

QuickTime has supported shortcut movie files since 
version 3-0. QuickTime version 4.0 introduced the Movie 
Toolbox function CreateShortcutMovieFile, which w F e can use 
to create a shortcut movie file. But the structure of shortcut 
movie files is so simple that we can build them ourselves. 
Let's see how ro do this. 

lhe format of shortcut movie files is (to my knowledge) 
currently undocumented, but ifs quite simple; the shortcut 
movie file consists entirely of a single movie atom, which in 
turn contains a movie data reference alias atom (of type 
MovieDataRefAliasAID). This atom contains a single data 
reference atom (of type DataRefAID). Finally, the data reference 
atom is a leaf atom that contains die type of the data reference 
followed immediately by tile data reference itself. Figure 1 
shows the general structure of a shortcut movie file. 





j *+16 

jr +8 

X 

data reference atom 
data 

fliOOV 

mdra 

dref 


Figure L The structure of a shortcut movie file . 


It’s easy enough to create a file that has this structure. 
The only thing we don't yet know is what a data reference 
is, to put into the data reference atom. In the next QuickTime 
Toolkit article, well take a long look at data references; for 
the moment, we ll just suppose that a suitable data reference 
is passed to us. (To look ahead a bit, a data reference is a 
handle to .some data that picks out a movie file or other file. 
For instance, a URL data reference is a handle to the NUId- 
terminated string of characters in the URL.) Listing 8 shows 
the function QTShortCuLCreateShortculMovieFiie that takes 
that data reference and data reference type and then builds 
a shortcut movie file. 

Listing 8: Creating a shortcut movie file 

QTShortCut CitraleShortcutMorfeMIe 

OSErr QTShottCutJ3reate!!>hortcutMuvieFlle (Handle theDataRef. 

OSType theD&taRefType, FSSpeePtr theFSSpecPtr) 

I 

long royVeraion = GL; 

USKrr myErr * nnErr; 

rayErr - Gestalt(gesLaUQulckTime, fijsyVarsioa): 
if (aiyEtr != noErr) 
goto bail; 
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if (((tuyVersion >> 16) & Oxffff) >= 0x0400) I 
// were running under Quicklime 4.0 or git iter 
nsyErr - CreateShortcutHovieFilettheFSSpecPtr. 
sigMoviePlayer♦ 
saCurrentScript, 
createHovieFileDeleteCurFile | 

c reateMovieFileDontCreateResFile. 
theDataRef. 
theDataRefType); 


J else t 

// we ir running under a version of QuickTime prior to 4.0 

OSType myD s t aRefTyp e; 

unsigned long myAtoiuHeaderSize; 

Ftr utyData = NULL: 

Handle myAtom s NULL: 

// create the atom data tJiai goes into a data reference atom (we will create this 
// atom's header when we create the movie atom that contains it); the atom data is 
// the data reference type followed by the data reference itself 
layDataRefType - EndianU32_NtoB(theDataRefType): 
myAtomHeaderSize * 2 * sizeof (long) : 

// allocate a data block and copy the data reference type and data reference into it 
myData “ NewPtrClear(sizeof(OSType) + 

GetEandieSize(theDataRef)): 

if (my Bat a = NULL) 

goto bail: 

BlocJtMove {&my0ataRefType, myliata. sizeof (OSType)): 
BlockMove(’theDataRef ♦ (PtrHmyData + sizeof (OSType)) * 

CetHandleSize(theDataRef)): 


// create a hamfle to contain the size and type fields <jf die rmivie atom, as wdl as 
// the size and type fields of die movie data reference alias atom contained in it 
// ami of tin 1 data reference atotn conuincd in the movie riant reference alias akuu 

myAtom - NewHandleClear (3 * nyAtonHeaderSlze): 
if (myAtom NULL) 
goto bail: 

// fill in the size and type fields of the three atoms 

-((long *) ('myAtotn + 0x00)) - EndianU32 NtoBCD * 

myAtomHead erSize) 4 GetBtrSi ze (myData)): 
'((long *) ('ntyAtom + 0x04)) « EndiflnU32_NtoB(MovieAlD): 

* ((long *) CmyAtom + 0x08)) “ EtidianU3?._NioB( (2 * 

myAtomHeaderSize) + Got PUSize EmyData)): 
•[(long *)(*jnyAtoiE + 0x00) * 

End i s nl 13 2 _N L oB {Ho v i eOat a Ref A1i a sAI D); 

* ((long *) (‘myAtotn + 0*10)) = EndisnU32_NtoB{(I - 

nyAtom!leaderSize) + GetPtrSize(aiyData)); 
*{(long *) (-cnyAionv + 0*14)) « EndianlD2_NtoB(DataRefAID): 

// concatenate the data in my Data unto the end of the movie atom 

my Err - Ptr Andtiand (tnyUat a , myAt on, Get Ft r S i z e (my Da t a )); 
if (myErr 1 st noErr) 
goto bail: 


// create the shortcut movie file 

myErr “ QTShortCut^WrlteHandleToFiletmyAtom. 

thsFSSpacPtr): 


bail: 

if (myData != NULL) 
DlsposePtr(myDat 0 ); 


if (nyAtom!“ NULL) 

DisposeHandia(myAtom); 

) 


return(myErr): 
i 


Our function QTShortCuLCreateShortcutMovieFite calls the 
Movie Toolbox function CreateShortcut MovieFile if it's available; 
otherwise it creates Lite movie atom itself, by building up three 
consecutive atom headers and then appending the data reference 
type and data onto the end of those atom headers. lL writes the 
entire movie atom imo the specified file by calling die 


QTShortCuLWriteHandleToFife function. (WcVc already 
encountered a version of this function, called 
QTDX_WriteHandleToFile; see “In and Out" in MacTecb, May 2QQ0J 

Atom Containers 

QuickTime version 2.1 introduced a new way to store 
information that greatly facilitates creating hierarchical 
collections of daLa and retrieving data from those collections. 
The basic ideas are very simple: ai the root of the data hierarchy 
is an object called an atom container ; Inside of on atom 
container are other objects, called atoms. (If we need to 
distinguish these atoms from the ones weVe been considering 
up to now, well call them atom container atoms.) An atom can 
contain other atoms, in which case it is a parent atom. The 
atoms that are contained wiLhin a parent atom are called its 
child atoms . If an atom contains only data (and no other atoms), 
it is a leaf atom. The data in a leaf atom is always in big-endian 
format. (Well, almost always; well encounter an exception to 
this rule in a little while.) 

An atom has an atom type and an atom ID, A parent atom 
can contain any number of children of any type and ID. The 
only restriction is that, for a given parent, no two children can 
have the same Lype and ID. So we can uniquely identify an 
atom by specifying its parent, its type, and its 1LX (For an atom 
that is contained directly in the atom container, the atom 
container is considered to be the atom’s parent; the special 
constant kParentAtomlsContainer is used to signal this fact.) We 
can also identify a particular atom by specifying its parent, its 
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type, and an index of atoms of that tyjie in that parent. 
(QuickTime supports yd a third method of identifying atoms, 
using ihe atom's position in the atom container, called its offset; 
we won t consider this way of identifying atoms here.) 

Let's consider a few examples. Figure 2 shows a very 
simple collection of data, where the atom container has just two 
children, each of which holds a long integer that represents the 
length (in millimeters) of a lizard. These leaf atoms both have 
the atom Lype Izlrv. 


storntyp# 
sfomfD 
stem date 



Figure 2 . A simple atom container. 

Figure 3 shows a more complicated arrangement of data. !n 
tills case, the root atom container contains two parent atoms, both 
of type 1dat T (for “lizard data*). Within each Idaf atom are two 
children, which have different types. The atom of type Izln’ contains 
a long integer (as in Figure 1 2) and the atom of type InanrV (for 
iizard name") contains a string of characters, (Ibis is neither a C 
string nor a Pascal string; it's just the characters themselves.) Notice 
that hah W atoms have an atom ID of 1; this is okay, since those 
atoms have different parents. 



Figure .i A more complex atom container. 

Atom containers can be vastly more complicated than the 
ones shown in Figures 2 and 3. and they don’t have to exhibit 
the kind of nice symmetry we see there. On the other hand, 
some real-life atom containers are just that simple. But no 
matter how complicated they are, well use the same functions 
to build atoms and atom containers and to retrieve data from 
atom containers. Let's see how to accomplish these tasks. 


Creating Atom Containers 

The file Movies.h defines these types for working with 
atoms and atom containers: 


typedef Handle 
typgdef long 
typedef long 
typedef long 


QTAt omCo n t a1ne r; 
QTAtom: 
QTAtomType; 
QTAtornTTU 


Notice that an atom container is just a handle to some data 
(structured in a specific way, to be sure). This means that we 
can determine the size of an atom container by using Lhe 
function GetHandleSizc. That's about as much as we need to 
know about the way an atom container is stored in memory. 
The actual structure of an atom container is publicly 
documented, but thankfully we will not need to learn 
anything about that structure. The Movie Toolbox provides 
all the functions we'll need in order to create and use atoms 
and atom containers. 

We create an atom container by calling the 
QTNewAtomConiainer function, like this: 

QTAtamContairier myAtomContainer « NULL; 

myErr “ QTNewAtomConLBiner (AmyAtomContainer); 


If GTNewAtomContainer completes successfully, then the value 
of the variable myAtomContainer is a new, empty atom 
container. We can then add atoms to that container by calling 
GTI riser tChild. For instance, to add the two children shown in 
Figure 2 to this atom container, we could execute this code: 

myLong - Endiantm NtoB{i029); 
itiyKrr - QTInr.ertChildC rayAtomContainer ( 

kParentAtomlsContainer, 
kLizardLength. I. 0, 
sizeof (EiyLonft), My Long, NULL); 
my Long - EndianU32_NtoB(n5S); 
myErr - QTtnaertChild( myAtotoCofita trier, 

kFarentAtomlaCon ta t ner * 
kLizardLength, 2 , 0, 
aizeof CtcyLong). MyLong, NULL): 

The second parameter to the GTinsertChild function specifies the 
parent atom of the child we re inserting. Here, you’ll notice, 
we're using the constant kParentAtomlsContainer to indicate that 
the parent atom is the atom container itself. The third and fourth 
parameters specify the type and ID of the new atom. The fifth 
parameter is the desired index of the new atom within the 
parent atom; we don't care about the index here, so we pass 
the value 0 to indicate that the new atom is to be inserted as 
the last child of the specified type in the parent atom. 

The sixth and seventh parameters m QTSnsertChild specify 
the number of bytes of data to be added to the atom, along with 
a pointer to the atom data itself. The last parameter is a pointer 
to a variable of type QTAtom, in which GTinsertChild will return 
to us an identifier for the new atom; we don't need that 
information here, so we pass NULL in that parameter. 

We can create a hierarchy within an atom container by 
inserting parent atoms and then adding some children to those 
parents. We also nil) GTinsertChild to insert a parent atom, but 
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we do not need to specify any data or data size; instead, we 
specify a variable of type GTAtom in which the identifier of the 
new parent atom is returned to us. 1 tere s an example: 

QTA t oil my Li za rdAtom; 

myErr — QTinseriCMldf myAtonCoriTainer * 

kPa rp.otAt oial s Container, 

kLizardBata, I* 1* Q, NULL* 
SmyiilzardAtam) ; 


Ihen we can insert a child atom into this parent atom, like this: 

myErr ^ CTl*1ns&rtChi Id ( myAtonContaiimr , 
myLizardAtom. 

kLizardName, 1, 1. 
strlen(thf^izardName) h 
t he Li zst r d Na in e. NULL): 

Note that the second parameter here is the parent atom that we 
just created. If we insert another atom (this time of type 'IzInT 
into the parent and then repeal the whole process for the 
second lizard, we'd have the atom structure shown in Figure 3 

Finding Atoms in Atom Containers 

If we are given an atom container, it s almost as easy to get 
data out of it as it is to put data into it. Hirst we need to Find the 
atom whose data we want: The standard way to do this is to 
start at the top of the hierarchy anti gradually descend until we 
find the parent of the desired atom. Then we can get an atom 
identifier of the target atom by calling the QTFindChffdByJD 
function. For example, if myLizardAtom is the parent atom for 
the atoms that hold the data about our lizard Avrif then we can 
get the name atom by executing this code: 

myNameAtoro “ QTFindChildByID(jnyAtomContaiiier, 
raylJ xnrdAtotn, 

kLizardName* 1, NULL); 

QTFindChildBylD actually inspects kith die type and ID passed to it 
(not just Lite ID, ax the name might suggest). 

Tile Movie Toolbox provides a numlx.r of oLher functions that 
are useful for finding specific atoms, including 
QTCountChildrenOfType. QTFindChildBylndex, QTGetNexlChildType. 
and GTNextChildAnyType. 

Getting Atom Data 

Once we’ve found a leaf atom, we can get die data from 
that atom in several ways. If we want a copy of the atom 
data that will persist even after weVe disposed of the atom 
container, we can call QTCopyAtomDataToHandle or 
QTCopyAiomDataToPlr, passing in a handle or pointer to a 
block of memory that’s big enough to hold the leaf atom 
data. If, on the other hand, we just want to took at the atom 
data and don't need a copy of it, we can call the 
QTGetAtomDataPtr function, which returns a pointer to the 
actual leaf atom data. If you plan to make calls that might 
move memory, then you should call QTLockContainer before 
calling QTGetAtomDataPtr; then call QTUnlockContainer when 
you are done w ith the data pointer. 


If we want ro retrieve our lizardN name, we could make 
this call: 

CTlXtetAlomDa tapt r (tHyAtflmCnntainer» myNameAtcm. kuiyNajEeSize* 

&myNanieData): 


If QTGetAtomDataPtr completes successfully, then myNameData 
points to die string of characters lliat make up the name, and 
myNameSize contains die size of that name. 

Internet Connection Speed 

For our first real-life encounter with atom containers, 
let’s consider how to get and set the user’s Internet 
connection speed preference. The user can set a preference 
in the Connection Speed panel of the QuickTime™ Settings 
control panel, shown in Figure 4. 


1 QuickTime”* Settings 


TiZ ^ 


Connection Speed 


ZI 


QuickTime will choose among multiple versions of 
internet media based on the connection speed you specify. 


014.4 Modem Q 112K Dual ISON 

Q2B.8/33.6 Modem ®TI 

Q56K Modem/ISDN O Intranet/tftN 

SflHotu Multiple Simultaneous Streams 
QcickT; me s default is to play one streem et a lime. 
Use this option to eUow playback of multiple streams 
simultaneously. This may degrade performance If 
your available bendvidth is exceeded. 


figure 4 The Connection Speed panel. 


QuickTime uses this setting for various purposes. For instance, 
if a user wants to play an alternate data rate movie File located 
on a remote server, QuickTime uses this connection speed to 
select the correct target movie. (An alternate data rate movie file 
is a movie file that references other movies, each tailored for 
downloading across a connection of a certain speed.) 

We can retrieve the user s current QuickTime preferences 
by calling the GalQuickTi me Preference function, like this: 


snyErr = CetQiiickt'iincPrcferenrR (Connect ionS peed PrefsType * 

fonyPrefsContainer): 


The first parameter .specifies the kirn! of preference we wish to 
retrieve, and the second parameter is the address of an atom 
container in which the requested preference data is returned. 
It’s up to us to dispose of that atom container when we are 
done reading data from it, In the present case, when we retrieve 
the Internet connection speed, the atom container contains an 
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atom of type ConnectionSpeedPrefsType whose data is 
structured as a record of type ConnectionSpeedPrefsReeord, 
defined like this: 


QTDiaposeAtomComainet(myFret^ContainerJ: 
I 

return(mySpced); 


struct CounectlonSpcedFrefsRecord I 

1ong coimectionSpoed: 

I; 


This record contains a single field dial, indicates the number of 
bytes per second that the user’s Internet connection can 
support. The file Movies For mat h defines a set of common 
values: 


ctium I 

kDataRatel ViModemRate 
kUataRate2 SSHodemRa r e 
kDataRatelSDNRare 
kDataRatpDual TSDNRat, e 
kDataRateTlRate 
kDaraRatelnfiniteKate 
U 


~ 1400, 

- 2 R00, 

* 5600* 

* 11200. 

- 150000L, 

- OxTFFFFFFF 


Note that we haven't performed any endian swapping 
on the value we read from ihe connection speed preferences 
record. That's because the data in this particular atom 
container is stored in its native-endian formal. This is an 
exception to the general rule that data in atom containers is 
big-endian. A user's QuickTime preferences are not 
designed to be moved from machine to machine, so there is 
no need to enforce big-endian byte ordering. 

Listing 10 shows how we can set a user's internet 
connection speed. In general, we should lei the user decide the 
connection speed preference, but it can sometimes be useful to 
do iliis programmatically. 


Once we've received an atom container from 
GetQuiakTimePreference, we can use the QTFindChifdBylD 
function to find the child atom of type ConnectionSpeedPrefsType, 
Then we get die atom data by calling the QTGetAtonnDataPtr 
function. Finally, we can read the value stored in the 
connectionSpeed field, to find the current connection speed 
preference. Well return this value as the function result, whether 
or not it s one of the predefined common values. 1 1 any error 
occurs, however, well return the value kDataRale28SModemRate, 
which is a reasonable default. Listing 9 shows the complete 
function GTUtils„GetUsersConneclianSF>eed. 

Listing 9; Getting the user’s Internet connection speed 
preference _ 

QTl; tils_Gct UsersConj iceiionS peed 
long QTUtils.GetlfsersCnrmflrtlonSpeed (void) 

i 

QTAtomContaimr myP refs Container = HULL; 

QTAtoia myFrefEAtom “ Q; 

Connect tonSpeedPrefsitecQrd myPref sRec; 

long my Data Size w QL; 

long mySpeed “ 

kDaiaRaie288HademRate: 

Ptr myAlomData = MULL: 

OSErr myErr = noErr: 

myErr = GetQuickTtmcPteference (Connections peed? ref RType, 
MnyPrefsContainer); 

if (myErr = noErr) E 

// find die mom of the desired type 

my?refsAtom - QTFindChildBylD (tnyPrefsConLaiiivc, 
kParnntAtomrBConi airier, 

Connect IonSpeedPrefsType. 1, MULL): 
if (rayPrefsAtom != 0) l 

// read the data contained in that Jioirt and verify that ihe data is of the 
// size we are expecting 

QTGetAtoniDatap1 1 (rayPref ^Container , niyPrefsAT.oii, 

6myDataSize. kmyAtonDnra): 

if (inyDataSize =** sizeof(ConnectionSpeedFreraReeotd)) E 
// read the connection .speed 
myFrefsRec - 

*(ConnectlonSpeedPrefsKecord 1 JmyAtomData; 
mySpeed - myPrefaRec.connectionSpeed: 
l 
J 


Listing 10: Setting the user’s Internet connection speed 
preference 

QTl ftils_5ct UscnsConj iccliortS peed 

OSErr QfnJtiia.SetUsersConrvact ionSpeed (long theSpeed} 

I 

QTAtojjsConta t nor rayPrefsCo&tai.nor ” BULL; 

Connor r i onSpeed?refsKecord myPrefsRe c.: 

OSIrr myErr - noF.rr; 

rayErt — QTNevAtomContainer(tayPrefsContsinor): 
if (myErr — noErr1 1 

myFrefsRsc* connectionSpeed _ theSpeed; 
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myEr r - QTInsertChild (myPrefsCorrtalner, 

kPattitaAlomTsConta\ne r t 
ConnectionSpeedPrefsTyp**, 1, 0, 
eizeof (ConnectionSpeedPrcfaRerord), 
&myPrtfsRec. NULL): 

if (myErr “ noErr) 

myKrr - SciQu ickTimeP reference( 

Cornua l longpeedPrefsType, myPrefsCont airier); 

QTDisposeAvomContairier (myPrefsCoivtalrier) ; 

I 

return(nyEer); 

I 

QTUtits_SetUsersConnectionSpeed creates a new atom 
containers inserts a single child atom into the container that 
holds the desired speed, and then passes lival container to the 
SetOuickTimePrefererrce function. Once SetOuickTimePreforerrce 
returns, we am safely call QTDisposeAtomContarner to dispose 
of die atom container we created 

Movie Tracks 

You might recall that in an earlier article ("Opening 
The Toolbox” in MacTech, March 2000), vve saw how¬ 
to write an application that plays one QuickTime 
movie inside of another QuickTime movie. The 
embedded movie (what we then called the "picture-in- 
picture movie”) could have looping characteristics 
different from those of the main movie. For example, 
the embedded movie could keep looping over and 
over while the main movie played though once and 
then stopped. And, in theory, the embedded movie 
could play at twice its normal speed while the main 
movie played at, say, half its normal speed, (We didn't 
actually provide this alternate speed capability, hut ii 
would be easy enough to add.) 

The only drawback to this was that we needed the 
special playback application QTMooVToolbox to make 
it all happen. Wouldn’t it be nice if we could create 
movie files with these capabilities, so that they would 
play bac k using any QuickTime-savvy application? This 
is precisely what’s offered in QuickTime 4/1 with the 
introduction of movie tracks managed by the movie 
media handier By adding movie tracks to an existing 
QuickTime movie, we can effectively embed an entire 
QuickTime movie into dial movie. (This capability is 
sometimes called the movie-in-movie capability; the 
embedded movie is also called the child nwric\ while 
the main movie is also called the parent movie ) 
Figure 5 shows one movie embedded within another 
movie using a movie track. 



Figure 5. A child movie inside of a parent movie . 

Remember that the looping characteristics and 
playback rate of a movie are associated with the movie's 
time base. Prior to QuickTime 4.1, it was possible to 
create movies with overlaid video tracks, but all the 
tracks in the movie shared the same time base, the time 
base of the overlaid track is slaved to that of the other 
lracks. What movie tracks bring to the table is the ability 
to have nan-staved time bases in a single movie. That is 
to say, each child movie can have its own time base, 
resulting in looping and playback rate characteristics 
independent of those of rhe parent movie. 

Adding a Movie Track to a Movie 

So let's see how to create movie tracks. Suppose 
that theWindowGbject is a window object for an open 
QuickTime movie file and that theDataRef and 
theDataRefType are a data reference and a data 
reference type for some oilier QuickTime movie file. 
Then we can call the QTMIM_AddMovieTrack function 
defined in Listing 11 to add to that ripen movie a movie 
track that references that file. (Once again, well 
postpone discussing data references uniiI the next 
article; for now, ail we need to know is that they pick 
out QuickTime movie files, either on the local machine 
or elsewhere on the Internet.) 

Listing 11: Adding a movie track to a QuickTime movie_ 

Ql‘MJM_AddMovicTrack 

OSErr QTMIM_AddMovieTratk [WindovObjset theWindowQbject. 

GSType theDataRef Type 1 , Handle theDataRef) 

I 

Movie myMovie m NULL; // the parent movie 

Track myTrack “ NULL; // themoviefrock 

Media myMcdia * HULL; // the movie imcl/fc media 

OSErr rayRrr w paramErr; 
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it ((theWindowObject NULL) | 

CtheDataRef 

goto bail; 


NULL)) 


myMovie - C**th©WindowObject)*fHovie; 


We'll begin therefore by calling QTNewAlomContainer 
to create a new atom container; since this container will 
serve as our media sample, well call it mySampfe: 


// crrjtc thr movie track uric) media 

myTraek « NewMo vieTrack (myMovie, 

CixRatio(kChildMovieWidth, 1) t 
FixR&tio(kChildMovieHeight, 1), 

kFullVolume); 
myErr ■* GetMoviesError0; 
if (myErr noErr) 
goto bail; 

my Mott i a ~ NewTruckMed la (myTrack ♦ MovieMcd 3 a Type . 

kMovieTiraeScale. NULL* 0); 
mylirr = CetMoviesError () : 
if (myErr 3* noErr) 
goto bail: 

// create the media sampled) 
fttyEr r - Eegl nMed i a Ed i t s ( my Med 1 a) ; 
ir (myBrr I- noEre) 
goto bail: 

myErr — 

QTMIN__AddMovieTrackSampleToMedia(theWindowOb ject , 

myHedia* theDataRefType, theDataRef): 
if (myErr !“ noErr) 
goto bail; 

myErr - EndMediuEdita(myMedia); 
if (myErr J= noErr) 
goto bail; 

// add the media to the track 

myErr = Insert Med i a TrttoTrack(myTraek. 0* 0* 

Get MediaDurat \ on(myMedis) , fixed I): 

bail: 

return(myErr); 

J 


There is absolutely nothing new about this function. 
ITs virtually identical to the function 
QTMM_CreateVideoMovie that we encountered in an 
earlier article (see "Making Movies" in AfacTecb, June 
2000). The only real difference is that we've created a 
media of type MovieMediaType; also, here we call 
OTMliyi^AddMcvieTraokSampleToMedia to add media 
samples to the new track, while earlier we called 
GTMM_AddVideoSamplesToMedfa. 


myErr = QTNewAtomContaIner{&mySamp1e): 

Into this new atom container we want to put an atom 
of type kMovieMediaDataReference, whose data consists 
of the data reference type and the data reference of the 
movie file that is lo be the embedded movie. We can 
create the atom data like this: 

myData = NewPtrClear(sizeof(OSType) 3 

GatHandleSize(theDataRef)): 
myType = EndianTJ32_NtoB£ theDataRef Type) ; 

B1ackMove(&myType, myData- alzeof(OSType)); 

BlockMove£ *theDaia[<ef, inyDaia + aizeof (OSType) . 

GetHandleSize(theDataRef)): 

Then we can insert the atom into the atom container by 
calling QTInsertChild: 

myErr = QTlnuer LChild (my Sample * 
kParentAtomlsContainer, 

kMovieMediaDataReference, 1, 1, 
GetPtrSize(myData). myData, NULL); 

At this point, we could call AddMedtaSample to add 
the atom container mySample as the single media sample 
of the movie track. Bul we'd like the embedded movie to 
stait playing automatically when the parent movie reaches 
the start time of the movie track, which is not the default 
behavior. To have the embedded movie automatically 
start playing, we need to add another atom to the atom 
container, of type KMovieMadiaAutoPlay. 

myBoolean - true: 

myErr = QTIneertChild(mySample, 

kPa rent At oral sCont.a i ner . 

kMovieMediaAiitoPlay, 1, i, 
sizeef (wy Bool can) * AmyBootean* NtJLL) : 

Now we can create a sample description and add the 
atom container to the movie track media. Listing 12 shows 
our function OTM!M_AddMovieTrackSampteToMedia for 
adding a media sample to a movie track. 


Creating a Movie Track Media Sample 

By now you might l^e wondering what this has to do 
with atom containers. The answer is simple: the media 
sample for a movie track consists of an atom container whose 
atoms specify the movie to lie embedded in the main movie, 
as well as some of the playback characteristics of the 
embedded movie, fn other words, the function 
QTMiM_AddMovieTrackSampleToMedia needs only to create an 
appropriate atom container and pass that container to the 
AddMedtaSample Function, 


Listing 12: Adding a sample to the movie track 
media 

QTM1M AddMovitTratkSampkToMtdia 

OSErr QTMIM AddMovieTraekSampleToMedia 

(WlndowObject theWJmdowObJeet. Media theMedla* 
OSType? theDataRefType . Handle theHataRef) 

( 

/fpragma unused (theWindovObject) 

QTAtomContainer mySampie " NULL: 

QTAtom myRegionArom; 

SampleDescrlptionKandle mylmageDesc « NULL; 

Ptr myData ” NtJLL; 

OSType tnyType; 

Boolean myBoolean; 

OSErr myErr = paiaraErr; 
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// create a new atom container to hold the sample data 

inyErr - QTNctwAromGonta Iner (6my$ample) : 
if CmyErr != noErr) 

goto bail; 

// concatenate ihe lLuu reference type and data reference 
// into a single block of data 

myOata = NewPtrCIear(ntseof(QSType) + 

GetHandleSlze(LheDataRef)); 

if (myData — NULL) 
goto bail: 


// convert the data to big-endian format 

myType “ EndianU32 NtoB(rheDataRefType); 







E 


B1 orkMo VR { kmyTypo t inyData, s Izeof(OSType)) ; 
RloekMovO(* tbeDataRef, myUata +■ sizeof(QSType). 

CetH&ndleSize(theDataRel)); 

// add an atom of type k Movie Media Data Reference 
// to the atom container 

myErr — QTlnsertChild(mySample, 

kFatenrATomTsCon trainer, 

kHovIcMediaUaiaReference. 1, l* 
GetPtrSize (myData) * myDara . NULL): 
if (myErr f= noErr) 
goto bail: 

// add an aulo-suri atom 

tnyBoolsan “ true; 
tnyErr -* QTTnsertChild 

(niySample, kPitrent Atontl sContainer , 
kMovieftediaAirtoPlay. 1, 1. 

sizeof(myBoolean). &myBoolean. NULL); 
if (myErr I* noErr) 

goto bail: 

// create a sample description 

mylmag^Denr ^ { Samp 1 eDesc rip LibnMaiidle) 

NewHandleClear(sizeof(SarapleDescription)); 
if (mylioageDeac ““ NULL) 

goto bail: 

(**rayImagnDe»c),deseSize ~ 
sizeof(SampleDescription): 

(* *niyTmageDeflr.) ,dataForma t = Mov i cMediaType; 

myErr “ Ad dMocJia Sample ( 
theHedia. 
my Sample , 

0 . 

GetHandleSizeC(Handle)mySample). 

GetHovieDuration(GetTr ackMovie(GetMediaTracfc 

(theMed t a ))) t taylmageDesc , 

I , 

0 . 


NULL): 


bail: 

if CmyData !" NULL) 

DiaposePtr(rnyUata); 

if (myImagoDesc I" NULL) 

Dispoaedandle((Handle)myImageDese): 

if (mySample I* NULL) 

QTDisposeAtomContainer(mySample): 

return(myErr); 
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Notice 1 1 uit, as promised earlier, we call GetHandleSize 
to get die size of the atom container when we call 
AddMediaSampie. 


This Month’s Code 

This month, our sample code is scattered across 
four different sets of files. The updated version of 
QTInfo is called QTLnfuPkis and includes a new 
version of the QTInfo_MakeFifePreview function and all 
the utilities that we used to access the atoms in a 
QuickTime movie file. The code for creating shortcut 
movie files is contained in the snippet QTShortcut c. 
The code for getting and setting the user’s Internet 
connection speed preference is contained in the file 
QTUUlities.c (which has been part of every project 
weVe developed so far). Finally, the code for adding 
movie tracks It) QuickTime movies is contained in the 
project for the sample application QTMovieTrack. 
QTMo vie Track allows the user to configure a large 
number of sctLings for the new movie track, in addition 
to the auto-playback setting (which we considered 
earlier). Figure 6 shows the dialog box that 
QTMovieTrack displays to allow the user to configure 
a new movie track. 


SroTLIQHT 

seven times faster 


free demo 
www.onyx-tech.com 


Find memory errors automatically in source 
Code Fragment Support a 

Leah. Detection Q 

Toolbox Parameter Checking jm II 



Figure 6 * QTMovieTrack's Movie Track Properties dialog 

box* 

For a complete explanation of the slaving and scaling options 
illustrated in Figure 6 . see the document ‘QuickTime 4T, 
downloadable in PDF form from the location 
<hup://developer.apple,com/techpub$/quicktime/qtdevdocs/RM/r 
m Wha ts ne wQT. htm>. 


Conclusion 

QuickTime tries very hard to insulate us from having to work 
directly with the kinds of atoms that comprise movie files (the so- 
called “classic” or “chunk” atoms). I he Movie Toolbox provides an 
extensive set of high-level routines that we can use to create new 
movie files, open existing movie files, edit movie Hies, and so forth. 
Nonetheless, we’ve seen that there are occasions when we do need 
to internet with atoms directly. A good example of this concerns 
adding a file preview to a single-fork movie file. QuickTime currently 
provides no API to do this, so we are forced to work with the file data 
— the atoms — directly. Similarly, if we want to create a shortcut 
movie file on a machine that's running a version of QuickTime prior 
to 40, we need to work with atoms. 

By contrast, well encounter atom containers and their associated 
atom container atoms at virtually every step we take forward in our 
journey through QuickTime. Atom containers and their children 
provide an easy way to maintain hierarchical data, and they're backed 
by an extensive programming interface. So atom containers are now 
the repository of choice for storing and exchanging data. Well see 
them used in media samples, rween tracks, input maps, musical 
instruments, wired actions, video effect tracks, and fora large number 
of oilier uses. In other words. Internet connection speed preferences 
Lind movie tracks are just the tip of the ice foe, 

Credits 

The functions for getting and setting a user's Internet 
connection speed preferences are based on code by Mike Dodd 
in the Letter from the Ice Floe, Dispatch 17 (found at 
<http://developer.apple.com/quicktime/icefloe/dispatch017.html>. 
Thanks are due to Ken Doyle for reviewing this article and 
offering some helpful comments. 
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We’re giving you four days in October 
to catch up to the future. 



Announcing QuickTime Live! October 9-12 at the Beverly Hilton Hotel. With over SO million downloads, 
QuickTime" is last becoming the industry standard for multimedia content on the Mac*OS and Windows. At 
QuickTime Live! we’re presenting four days of exhibits, workshops and conferences to help you put 
Quicklime to work brilliantly-from CD content to web streaming. If you're a multimedia pm, it’s your 
future. Don't miss iL For details and registration information, visit our website, www.apple.com/quicktimelive. 
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SPEECH 

RECOGNITION 


By Erik Sea 


Speaking to your Software 


Making your application 
work well with IBM ViaVoice 
Enhanced Edition 2.0 

What Can I Say? 

It’s here! Talking to machines and 
having them respond and react has been 
the stuff of science fiction for decades, 
The promise has been so long in coming 
that the release of ViaVoice Millennium 
for Mac last year seemed to take some 
people by surprise — many a passerby at 
Mac World San Francisco was astonished 
by the speed and accuracy of the system, 
even in noisy shnwfloor conditions. 
Nonetheless, the combination of 
computational power and algorithm 
design has finally produced speech 
recognition software for the Mac that 
permit routine and productive use. 
especially as fast, new copper IBM 
PowerPC chips find their way into more 
and more Macs, 

ViaVoice Millennium, the first 
release, was a low-end product, 
providing dictation into a single 
appl lea tin n , Spea k Pa d, a n d non - 
customizable transfer scripts. Good for 
basic dictation, with a large, extensible 
vocabulary, dictation macros, and 
AppleScript support. ViaVoice Enhanced 
builds on this capability, adding new 
features such as direct dictation into 
selected applications and allowing 
customization of “built-in” functions 
through AppleScript. 


“Aha!" you say — “Direct dictation into selected 
applications, but what if Fm not among the 'selected 1 few?" Fair 
enough — IBM can only test and support a few high-profile 
programs (although the development team is always interested in 
testing new software for compatibility, particularly games), 

I lowever, the ViaVoice software doesn't prevent dictation into 
any application and. in many cases, the Mac OS and ViaVoice 
extensions that ship with our software are all you need — your 
application may already support dictation and correction 
without you writing a single line of code! 

Probably, though, you should write a line or two of code. 
This is essential for maintaining Lite awe and admiration from 
your employer, and I know that you really do want to anyway. 

ViaVoice Speech Technoiogy 

But. before we write code, let's talk about speech. Or speak 
about talk, and how the ViaVoice engine decides what words it 
thinks you uttered. 

Unlike earlier “discrete" speech recognition systems, which 
,..required distinct ... pauses .,. between... words, ViaVoice 
works with “continuous" speech, with no unnatural breaks 
between words. In consumer products, we're not quite to the 
stage where you can have conversations with your computer, or 
even record or transcribe a speech or a meeting, but for one 
person, sitting at a computer, speaking dearly and providing 
cues such as punctuation and formatting, recognition is really 
quite good. In any ease, there are other technologies that will 
need some work before you can say, 'Tea, Earl Grey, Hot” and 
get what you would like. 

Training 

Recognition accuracy is also improved by training, which 
allows ViaVoice to construct a mathematical picture of your 
voice, which il can then use with iLs models. 

The user reads a prepared story Is read to the system to train it 
— the system knows what the words are, and what they ought to 
sound like. By comparing these sounds to actual sounds, a difference 
can be calculated down to die individual sounds that make up a 


Erik has been working on Mac development throughout modern history, and, in that time, has done everything from drivers 
to GUI, and from telecom to graphics processing. Last year in search of new challenges, he joined the ViaVoice for Mac team 
at IBM in Florida, and has led the recent release of the Enhanced Edition, which, it is noL commonly known, is written 
specifically for the Mac from the ground up. In his spare time, he breeds noncamivorous slinkys in the desks of unsuspecting 
coworkers. You can reach Krik ai esea@us . ibm.ee®. 
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word. For example, suppose when I talk I make my Ts sound like 
Ds much of the time “butter" sounds more like “budder” when I .say 
it, but someone else my veiy crisply say "butter”. 

Once this picture of my voice exists, Via Voice can predict 
with some level of accuracy how 1 might say a specific word. 

Vocabularies and language Models 

Tile ViaVoice vocabularies (sometimes called 
“dictionaries”) and Language Models arc basically large 
databases of word pronunciations and word positions 
relative to other words, respectively. You can add your own 
words to the vocabulary, and teach Via Voice what they 
sound like — an extension to the spell dictionary sort of 
operation you may be familiar with for word processors. 

Language models are a bit trickier to explain. Start with a large 
number of typical dictation documents, feed diem into a shredder, 
and out pops a language model at the other end. Well, maybe not 
a shredder. The secret Is they are dissected by elves. Honest. 

However they are created, you can think of a language 
model as collections of trigram (comprising three consecutive 
words). The probability that a given spoken word really is a 
specific written word is influenced by the word around it, and 
trigrams capture this relationship. By no means should you 
equate “language model 11 with “grammar” they are not at all 
the same, as grammars reflect complex usage rules that are 
difficult even for most humans to apply correctly ad the time. 

To illustrate further, consider the sentence “Please write 
to Mr. Wright right away." We hand this to the elves, who 
produce trigrams along the lines of those shown in Figure 1. 
Now, assuming that you don t pronounce “write”, “Wright 11 , 
and "right” in noticeably different ways, how does 11 us 
system figure out which sounds correspond to which words? 
The trigrains from Lhis sentence, combined with other 
trigrams from other sentences, end up with results like “If it's 
preceded by l Mr/ f it’s most likely £ Wright*”, and so on. 
ViaVoice is very good at this kind of thing and, where it 
makes mistakes, it can even learn not to make them in the 
future through correction, which improves accuracy. 


Sample Sentence: 

Please write to Mr. Wright right away. 

Resulting Trigrams; 

<Ptease,write,to> 

<write,to.Mr> 

<to,Mr.,Wrighl> 

<Mr, Wright, right> 

<wright,right,away> 

<right,away,[periodj> 


Figure L Basic Trigram Construction, 


By the way, you might want to take a moment to consider 
die word “to 11 in the Figure 1 example. How does ViaVoice know 
the difference between “to" and “two" and ‘Too 11 w'hen they all 
sound the same? The answer, once again, is by context, as 
captured in the trigrams! 


The more you use it, the better it gets 

“7 find it interesting that the software is learning about me 
while l am teaming about it. v 

This customer remark is based on the realization that, as you 
use ViaVoice, it actually continues to improve your voice model. 
For example, if you add words that the system doesn't know, 
those get added to the model If you make corrections using rhe 
correction window (See Figure 2). those corrections get applied 
to the voice model. 



Figure 2 Correction Window — 
if your associate is actually Mr. ‘Right*. 

Also, if you have text documents containing phrases, words, 
and names that you expect to dictate often, you can analyze those 
documents, which will further update the voice models. ViaVoice 
Enhanced has extra facilities that integrate the document analysis 
features into dictation, so that you don’t need to store up 
documents and run the analysis program yourself. 

IL is not unusual to hear of accuracy improving from 95% to 
98% with persistent use. 


Splaking of Japanese 

And now. on to the code, and how ViaVoice adopts and extends 
the Mac OS to bring you dictation as seamlessly as Japanese. 

The Mac was probably the first platform to make 
internationalization a key design objective. As a result, many 
components of Mac OS, including almost all toolbox functions, are 
ready-made compatible with other languages and script systems. 

You’ve probably ail dca.lL with localization issues before, 
ranging from not hardcoding strings to not making 
assumptions about the size of the label on a button when 
translated. Some of you have no doubt dealt with the multi byte 
matters arising from making a product work correctly with 
Japanese, ranging from not being able to make byte = 
character assumptions to working nicely with Input Methods, 

With the distribution of Mac OS 9, it became easier for any 
Mac user to install multiple input methods, for languages such 
as Japanese or Korean or different eastern European script 
systems as well as the "default” (typically Roman) keyboard 
system. Previously, while such capabilities were available, 
input methods were not widely used outside of countries 
where they were absolutely required. 
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An input method traditionally allows you to enter text in a 
different script system by typing a few characters, pulling up 
palettes based on those Characters, and selecting similar symbols 
from those palettes. 

There are two forms of input associated with an input 
method: inline and bottomline, shown in Figures 3 and 4 
respectively. Inline input is generally preferred by users; 
hollomline input requires you to enter data in one place and 
have it show up in another place, in another font. Bottomline 
input also lacks the ability to go back and edit later. 


□ untitled 0 

0 


A. 

V 


M 


Figure 3 Direct inline support in Japanese. 



Figure 4. Japanese bottomline input 
{text entered in lower window). 

In designing Via Voice Enhanced direct dictation, we 
decided that we could use the input method architecture 
developed by Apple for non-Roman languages like Japanese, 
and use it for word-based input and correction, We did end up 
needing to extend the model slightly, as 111 describe later, but 
we did it in the background so that, in some circumstances, if 
you do the work to allow Japanese inline input, you also get 
Via Voice speech inline input and correction for free! 

TSM, TSMTE, IBM W Ik U 

These acronyms represent the key players in IRM Via Voice 
dictation into any application. 

Introduced way back in Mac OS 7,1, the Text Services 
Manager (TSM) has provided functionality for other languages 
(primarily multibyte languages) for years. With TSM, a savvy 
developer could write a few lines of initialization code, and then 


install 4 Apple event handlers that, much like AppleScript, 
performed operations like inserting text, showing and hiding the 
bottomline input window, and Lulling Lhe input method where a 
given text offset was. TSM is well-documented in Inside 
Macintosh: Text , forming all of chapter 8 . 

litter, Apple introduced the Text Services Manager for 
TextEdit (TSMTE), which eliminated the need to write any of the 
event handling code in applications that only used TextEdit — 
from this point, it was only necessary to initialize the manager 
and let TSMTE handle the rest. Tins functionality is well 
documented in Apple's Tech Note TE27 . 

Full inline input was not achieved until a new fifth Apple event 
was added. This is die GetText or gtxt 1 event, and it is only 
documented in a develop article by Tague Griffith (issue 29), or in 
Apple's Tech Note 70002 (which Ls only available in Japanese 1 ). 

For speech, wc determined diat the above was not enough. 
While we could have gone our own way with a completely 
different model and then tried to sell it to developers* we 
decided to, instead, augment Lhe existing TSM calls, by adding a 
couple of extra parameters to GetText, and adding another event 
which we call SetSeleetion, With just these iwo changes, we 
have the necessary and sufficient conditions for dictation and 
correction. Sure, we could do more with more events (and, may 
extend the system to enhance functionality in the future), but 
you're busy trying Lo figure nut how Lo get your software to run 
under Carbon, so we thought we'd cut you a break! Oh T and as 
you may have inferred, if you've relied on TSMTE for inline 
Support in Japanese, the changes to GetText and the addition of 
SeiSeleciion is done for you automatically. We’ll talk about these 
additions later when I present the implementation code. 

If you don’t use TextEdit exclusively, you cannot rely on 
TSMTE for Japanese input, and you will likewise need to do the 
work of handling the calls and adding the parameters yourself. 
But, even so, if you've done the work for Japanese (Japan being 
the second largest Mac market in the world), the incremental 
work for adding Via Voice support is bordering on the trivial! As 
J write this , it may also be necessary to write these handUms for 
Mac OS X, whether or not you use TextEdit. By the time you read 
this . we lt have a better idea of what the story is. Either way, the 
solution is not difficult, it's just a matter of not knowing which 
path will he required far Mac OS X. 

Adding thf. Ears 

By now, you're probably frothing at Lhe prospect of 
dictation-enabling your code. Let's get right to it. In Listing 1, 
you’ll see how F to enable TSM as part of your startup retinue and 
disable it as pan of quitting (Carbon Applications don't need to 
do this — tiie OS does it for you automatically). While you're 
enabling TSM, know that while you must set the 'high level 
event aware" bit in the SIZE resource, you do not need to set the 
bit “Use text edit services", because it is deprecated (relates 
actually to an earlier implementation prior to TSMTE)* 
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Listing 1: Becoming TSM Aware _ 

Determining if TSM is available, initializing it, and cleaning up 

This is more or less boilerplate code that is required for any application. Note that, 
under Carbon, you do not even need to make these calls, as the system will do them 
for you — that is, any Carbon application isTSM-aware without any special calls! 

Boolean IsTSMAvailable (void) { 

SInt32 version; 

Boolean available= false; 

// Note: gcstaltTSMgrAttr is not defined under Mac OS 9 
// so we use the gestaltTSMgrVersion selector instead... 

if (noErr = Gestalt (gestaltTSMgrVersion. Aversion)) { 
if (version >= gestaltTSMgrl5) ( 
available = true; 

} //if 
) //if 

return available; 

1 // IsTSMAvailable 

void StartTSM (void) { 

// Initialize TSM, and install our event handlers... 

OSErr err = noErr; 

if (IsTSMAvailable ()) { 

//if TARGET_API_MAC_0S8 

err = TnitTSMAwareApplication (); 

//end if 

// Install TSM event handlers here — see later section 
) //if 


gFontForce = GetScriptManagerVariable (smFontForce); 
SetScriptManagerVariable (smFontForce, false); 

) //StartTSM 

void CloseTSM (void) { 

// Clean up all TSM things, including our event handlers... 

SetScriptManagerVariable (smFontForce, gFontForce); 

if (IsTSMAvailable ()) { 

//if TARGET API_MAC_0S8 

(void) CloseTSMAwareApplication (); 

//end if 

// Remove AE handlers here... 

} //if 

1 //CloseTSM 

You’ll notice that there is no special “is ViaVoicc installed” 
code. Again, because we’re an input method, the code you write 
works whether we’re installed or not! 

If you’re only using TextEdit and dialog boxes, set the 
refcon field of your dialogs to kTSMTEInterfaceType and you’re 
done. Go talk to your computer for a while. Tell your 
friends/family/coworkers I said it was OK. 

Beyond TextEdit Support 

Although many applications can live with just TextEdit, the 
32K limit, among other things, lead many people to roll their 
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own or use ;i third-party code library such as WASTE (although 
now Apple has made a special MITE — multi-lingual text edit 
-— available). These will require implementation of five Apple 
event handlers. The complexity of these handlers, naturally, 
depends on how your code is laid out, but in general, you're just 
providing an external API to functions or data that you already 
have written, And you need to do 98% of this for Japanese 
anyway, so why not squeeze in the 2% for speech? Ill even write 
the code for you. Alternatively, you can use WASTE 
(WorldScript-Aware Styled Text Engine, by Marco Piovanelli) 
which is available in source code form all over the Web, and 
does much of the work (WASTE would need to be adjusted 
slightly to handle some of the modified events described here). 

But before we delve into the handlers themselves, some 
TSM terminology. The basics of TSM are discussed in chapter 7 
of Inside Macintosh: Text, and also in Tague Griffith's article in 
develop 29 (see links section), so 1 will gloss over most of that 
— the code i.s pretty self explanatory when read with those 
references in hand. Ironically, Tague even suggests that input 
methods might one day be used for dictation input! 

TSM keeps track of things on a document basis, where a 
document is a unique editable area of text. You’ll need to add 
some extra handling to your event loop, so thai TSM gels a crack 
at events it may need to intercept with TSMEvent(), and give TSM 
first crack at menu events with TSMMenuSelect() (you may have 
noticed that input methods typically have menus — the ViaVoice 
input method does not have a menu, but you do want to 
support Japanese too, right?). As well, when your TSM-aware 
documents become active and inactive, you need lo tell TSM 
with AcfivateTSMDocumentO and DeactivateTSMDocument(). 

input methods also might like to change the cursor 
(currently, die Via Voice input method does not do so, but others 
do and ViaVoice may in the future), so in your cursor- 
management routines, or at idle time, call SetTSMCursor(). For 
tliis to work, your mouse-moved region (the final parameter to 
WaitNextEveni() which most people lazily set to NULL) needs to 
lie a single point — since you have no way of knowing when 
TSM wants to change the cursor 

OK, that was pretty fa.sL, but as it’s l>ecn written before in 
the references above, I didn't want to repeat it. You can look at 
die sample application that comes with this article if you’re lost. 

The key part to dictation-enablemenL is the Apple event 
handlers. These handlers need to get installed for the input 
methods, including ViaVoice, to be able to extract information 
from your document content. ViaVoice doesn't vary much from 
the standard architecture, and I will highlight the differences. 

Position to Offset Event 

This event converts screen coordinates into an offset in your 
document. You receive a point, and return an offset. ViaVoice 
does not currently use this event. 

OSErr 

DoPos20ffset (Diaiogptr inBialgg. const AppleEverit* 
inAppleEvent, AppleEv^nt 11 otitKeply] { 


Size actualSize; 

DescType actualType: 

OSErr err s noErr; 

Boolean dragging “ false; 

Point cutrentPoint; 

SInt32 offset; 

Sint16 where; 

Dialog!temType dialogType: 

Handle dialogHundle; 

Rect dialogBounds; 

GrafFtr svPort: 

GetPort E&svFort); 

# i f TARGET..API MAC. OSS 
SotPort [inDialog); 

(felae 

SetPortDialogpQrt UnIMalog); 
frendif 

// Required parameter is a point 
if (err = noErr) { 

err * AEGetParamPtr (inAppleEvent* keyAECurrentPoint. 
typeQflPoint. ftactualType* &currentPoint* 
sizcof (currentPoint). &actuaISize); 

\ //if 

// Optiurul parameter is Tor dragging 

if (err 1=35 noErr) t 

(void) AEGetParamPtr (inAppleEvent* keyAEDragging* 
rypeBoolean. SiactualType. &dragging, 
sizeof {dragging), fractualSixt#: 

I //if 

// Nuw, wc should do all sons of calculations, hut, 

// TextEdit will mure or less do ULis for us uncc wc 
// figure* out if it's in the right plate,,. 

GlobaIToLocal (AcurrentPolnt): 

GetDialogltein {inDialog, kKdltTfeXtDialagltea, 

Stdialog'i'ype, fcdIalogHandle, HialogBounds); 
if fPtlnRect (currervtPoint. SdialogBmmds)) [ 

TEHandle diaiogTE - GetDiaiogTEHandle (inDialog): 
offset = TEGetOffset (currentPoint, diaiogTE); 
where = kTSMInside0fActiveInputArea: 

J else f 

where “ kTSMInsIdeOfActivetnputArea; 

) //if 

// Sluff the return values here 

if (err “ noErr) I 

err = AEPutPsramPtr [outReply* keyAEOffset, 

typ&Longluteger, ^offset* sizeof (offset)); 

l//if 

if (err — noErr) { 

err = AEPutParainPtr CoutReply. keyAERegiouClass. 

typeShortinteger, &where* fiizeof (where)); 

I //if 

SetFnrt CsvPort); 
return err; 

1 // DoPos2Gff$et 


Offset to Position Event 

The reverse of Position to Offset: return a global |>oint given 
a text offset. ViaVoice does not currently use this event* 

OSErr 

DoOffsetSPos (DialogPtr InDialog* const AppleEvent* 
inAppleEvent, AppleEvent' outRcply) I 

Size actualSize; 

DeseType actualType; 

OSErr err “ noErr: 

SlutS2 offset; 
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GrafPtr sypert; 

Point thePoint; 

TEHandle teHandle * GotDialogTEHandle (inDialog); 

Rect bounds : 

GetPort (&svPort); 

#if TAR{jET_Al ] l_MAC_OSB 
SetPort (inDialog): 
bounds “ inDialog->portRect; 

#else 

SetPortDialogPort (inDialog); 

GetPortBounds (GetDialogPotL linDialog)* Abounds); 
fendIf 


Size 

DescTyne 

OSErc 

AEDesc 

AEDesc 

AEDesc 

Sint32 

TextRange 

TEHantfte 


actuaiSize: 
actualType; 
err 

tfieTexTD^Etc 
theHi 1 i teGese 
rhoUpdateltesc 
f LxLength: 
thePinKange: 
teliandle 


noErr; 

II; 

M; 

M; 


SeripiUinguageReco rd sc ripiCode; 


GetMalogTEHand I q 


£inDialog]: 


// Required parameters containing firmed text, script 

// and tod length- 


// Required parameter is an offset position... 

tf (err = noErr) I 

err “ ABGetParamPtr (inAppleEventkeyAEDffset» 
typeLonglnteger, iaeLUalType* ^offset, 
sizeof (offset }, firactualSize); 

I //if 

// Convert the offset 10 a position, taking into 
// account whether it’s visible or not.., 

if (err = noErr) I 

thePoint - TEGetPoint (offset* teliandle); 
if ((offset < 0) H (offset > ( 44 teHandie).teLength]) 1 
err “ errOffoetT rival id; 

} else if (PrTnReei (thePoint, Abounds)) ( 
err " errOffsetlsOutsideOfView; 

I //if 
1 //if 

// Return the point (in global coordinates), and 
// die parameters of the text... 


if (err = noErr) t 

err - AFGctParamDesc (inAppleEvent, keyAETheOatO♦ 
LypeChar, &thefextDesc); 

) // If 

if (err = noErr) I 

// Note:“Inside Macintosh - Text" says rhb parameter 
// is imder keyAEScripflag, bin in practice it appears to 
// be under keyAFTSMSc rtptTag 

err = AEGeirPararaPiE (inAppieEvent, keyAETSHSrriptTag, 
typeliulWritingCode, iactuaiType, Script Code, 
sizeof (scriptCode). factualSize); 

I //if 

if (err = noErr) I 

// Note 'Inside Macintosh - Text“say's this parameter 
// is required, but in reality, it seems to he optional 
// and nut sent (and redundant with the actual s&e of 
// the data in theTfcxtDesc) we won’t use or rdy 

// cm it.., 

(void) AEGelParamPtr CinAppleEvent, keyAEFisiLcngih, 
typeLonglnteger t AactualType, frrixLength, 
sizeof (fixLength). AariuzilSize); 

) //if 


it (err == noErr) i 

LocalToGldbal {& LlifPoint) r 
I //If 

tf (err * noErr) t 

ere = AEPotFaxamPtr (outReply* keyAEFoint, typeQDPoint, 
SithePoint * sizeof (thePoint)) ; 

I //if 

if (err noErr) I 

err H AEPutParatnPt r (ootKepiy* keyAETextFont, 
ty peLon glut ege r» & ( 4 * t eHandle). txF out, 
sizeof (Slnt32)); 

I //If 

if (err «= noErr) ( 

Fixed theFixed w Long2Fix[(**teHandle).txSize): 

err - AEFutPacamPtr (outReply, keyAETextPointSize< 
typeFixed* &theFlxcd* sizeof (theFixed)); 

\ //tf 

it (err = noErr) { 

err - AEPutParsniPLr (cmtReply, keyAETextLindHeight* 
typeShortinteger, &( 4, teHandle).lineHeigru, 
sizeof (SIntlS)); 

J //if 

if (err = noErr) t 

etr = AEFiitfaraiuFtr (outReply, keyAETextLineAscent, 
fypeShort Integer, M “ teliandle). font As cent, 
sizeof (STnU.6)); 

I //if 

SetFcrt (svFort); 

return orr; 

1 //l)oOffsct2ft)s 


Vi pda it 1 Active Input Area Event 

This event is used to hilite an area of your document as 
requested by the input method. Via Voice does not currently 
use this event, 

OSH r r 

DoUpdateActivelnputArea (DialogPtr inbialog, const 

AppleEvent* inApplcEvt?nt, AppieEvent 4 /*outReply 4 /) j 


// Optional parameters hiiiU' range list, update range, 

// and Pin range: we don't use any of rhest. 1 

if (err = noErr) f 

(void) AEGo L RataraDesc (inApp1eEvent, koyAEH11iLoRange, 
typeTextRangeArtay. fiithaHiIit cUosc); 

I //»f 

if (err = noErr) I 

(void) AEGetParataDesr. UnAppIoEvent. keyAElIpdateRange„ 
typeTsxrRangeAt ray, itbeUpdateDesc); 

I //if 

if (err = noErr) I 

(void) AEGelFarajnFtr (InAppleEvent, keyAEFInRangc* 

typeTextRange, fiiactualTypOn AthePlnRango, 
sizeof (thePinRange), factual $ Ue) ; 

I //if 

//At this [mint,we need to he inserting text 
// most probably,. 

if (err = noErr) ( 
tfif TARGFT_APIJHAC_0S8 
STntfi iiState; 

- ilCetState ((Handle) thpTextDpsc .duLallandle); 
liloek ((Handle) tbeTextDefir,dnrnHandle); 

TEDelete £ teHand le): // Clean li rst« 

TEInsert (*(theTextDear.dniallandle), GetHandleSise 
((Handle) theTextboEc^daudlandle). teHandle); 
HSetState ((handle) theTextDesc*dataHandle, hState); 
ffelse 

// AEDescs arc opaque under Carbon. So we need 
// to allocate and copy using Lllc accessor APLs. 

// OK, fine... 

Size dataSize = AEGetDesrDataSize (AtheTextBesc): 

Handle dataCopy “ NewHandle (dataSlze); 

if (dataCopy != NULL) [ 

HLock (dataCopy); 

err = AEGetfieecData [SitheTextDesc, MataCopy, 
dataSize); 

I else ( 

Drr * mettiFullErr; 

I //if 

II (err — noErr) t 

i'EDelete (teHandle): // Clean first. 

TEInsert (*dataCopy, daiaSlze, teliandle); 
l //if 
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if CdataCopy 1- NULL} [ 
DisposeHandle (dataCopy); 

I //if 

(audit 
I //if 

// Clean up., 

Wold3 AKDisposaDesc UtheTextDesc j; 
(void) ARD1spn^eDesc (GtheHiliteBesc); 
(void) AEDispaueOnsc (ttbeUpdaxeDesc): 

return err: 

I // Dot;pditcActivclnpu (Area 


Get Text Event 

The GetText event is a mystical event introduced by Apple 
japan and, until recently, dcrcumenred only in Japanese. This 
event allows the input me I hod to request the application to 
return text that has already licen committed to the document* 
Via Voice uses this event to extract text for correction. 

More than that, however, Vi a Voice expects two additional 
parameters: the offset start and die offset end. Why is this? 
Because, unlike simple text-editing Input Methods, Via Voice 
distinguishes between the first utterance of die word u the n and 
die second — it actually keeps track of all the dictated text for 
a session, the relative words, and so on, in order to make 
correction work. If Via Voice were to allow correction simply 
based on the text of the word, all of the additional contextual 
information and even the audio data would lie useless! 

Thankfully, if you use TextEdit, the extra parameters are added 
for you by Via Voice, but for other wordprocessing situations, youll 
need to add them. Relatively painless, in most cases, since you 
probably know die offsets of the selection anyway! 

OSErr 

DoCetSelectedText (OialogPtr inDialo^. const AppleJSvenL’ 
CiiiAppleEvcnC/, AppleEvent* out Reply 3 


OSErr 

TEHandle 

SlntB 

STnt64 

Sinter 


err " noErr; 

teHandle = GetDIalogTEHandle (ioDialog); 

hState = HOt State ((Handle) teHandle): 

selStart - (“teHandle] selStart; 

selEnd “ (* ‘teHandle), selEntl: 


//The only required return is the current selected text 

HLock ((Handle) teHandle )i 
if (err = noErr} f 

err - AEPutFaratnPtr (out Reply. keyAETheData, typeText* 
6i(*teHandle} [selStart], selEnd snlSfart): 

1 //If 

// For Via Voice, we also add the numeric values of the 
// start and end of the selection within the text. 

if (err = noErr) I 

err - AEFutParamPtr (outReply, keyWStartSelentionParam. 
type$lnt64. SueIStart, sizeof (selStart)): 

l //if 

if (err = noErr) I 

err - AEPutParaasPtr (outReply, keyWEndSclcct InnParant, 
rypeSInt64, inelEnd, sizeof (selXnd)); 

I //if 

HSetState ((Handle) leHamJle. hState); 


return err: 

// DoGetSekaetfTeat 


Set Selection Event 

Hi is event is new and unique to Via Voice. For TextEdit, it is 
implemented for you in one of the Via Voice extensions (with 
one caveat of course: if you don’t expect the selection to change 
within your TextEdit fields, you may be surprised to .see it 
change, or if you duplicate the selection range in one of your 
own data structures, you may end up out of sync). 

Really, all this does is ask you application to change the 
active selection. This is necessary so that commands such as 
"correct the”' wall work as the user expects them, 

OSErr 

DnSetSelection (DlalogPtr inLUtilo^. const ApplnEvent - 
InAppleEvent, AppleEvent* AjutRcpfyV) I 

Size actualSize; 

DescType actualType; 

OSErr err 51 noErr; 

TEHandle rehandle = CtetDialoftTEHandle (inDialog); 

Sint64 selStart; 

SInt64 selEnd; 

Boolean doDraw - false; 

//Hiis is a VaVuice-spcdlk event Retrieve live 
// sc lection .and the optional draw event, ami do il. 
if (err = noErr) I 

err = AEGetParainPrr (inAppleEvent* 

keyVVStarLSelecttonParam, typeSInt64, fcactualType* 
fcselStart, slzeol (selStart), SactualSize); 

I //if 

if (err = noErr) I 

<‘rr “ AEGetParamPtr [inAppleEvent♦ 

keyWEtid Sole ctionFa ran, typeSint64, factualType, 
fitselEnd, sizeof UelEnd), fracttfaiSize); 

I //if 

if (err = noErr) f 

(void) AEGetParamPtr (inApplcEvent* 

keyWDrawSeleetionFarani, typeftoolean,, kactualType, 
AdoDrav, sizeof (doftrairf). fcaclualSlze): 

1 //if 

// Clip off i he ends to Text folic range... 

if (err — noErr) I 
if {selEnd > Dx/fffJ ! 

selEnd - 0x7fff; 

I //if 

if (selStart > 0x7fff) I 
selStart ~ 0x7fff; 

! //if 

if (selStart < 0) I 
seiStart = 0: 
err * paramErr; 

I //if 

if (selEnd < 0) \ 
aelEnd = 0; 
err = paramErr; 

1 //if 
I //if 

if (err = noErr) [ 

TESetSelect (selStart h 0x7fff, selEnd 6 Qx7t±f, 
teHandle): 

I //if 

if ((err ” noErr) && doDraw) [ 

// We would optionally draw lure, bul [BrtSdcet docs 
// tlmr anyway there’* mi point I lie idea i> liiai the 
// screen will flicker if you honor this optional 
// parameter.. 

I //if 

return err; 

I //DaSetSeJection 


Fine Tuning 

The Mac OS is a cooperative multitasking system. ViaVoice 
direct dictation involves the cooperation of at least four different 
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applications, all of which need a slice of time. See Figure 5 for 
an overview of how the components interact. The recognition 
engine, in fact, will shut off if it doesn't get enough time to 
handle the incoming audio stream which, like the real world, 
isn't very cooperative. Audio data is big, so the amount of time 
before a shutdown is small. You can simulate this by clicking on 
a menu in Mac OS while the microphone is on. 



Figure 5 interprocess Communication within Via Voice — and 
to your application — requires that everybody stare the 
processor equitably! 


So, what you need to keep in mind liiai your application, when 
in the foreground, should be as friendly as it can lx. 1 with the oilier 
processes, particularly tailing WaiiNexiKvent frequently enough that 
the recognition engine gets time to process audio, the dictation 
manager gets enough time to assemble words and send them in 
your application, and the VoiceCenter gets enough time to 
communicate status and feedback to the user Some applications try 
to avoid WaitNcxthvent in order to improve their own apparent 
performance, but if you do this with Via Voice, you wont get very 
good throughput, and you may even starve the engine to shutdown. 

Not everything that you can type into is appropriate for 
dictation — sure, you could .say t\m text Is text, but dictation isn’t 
really the same as data entry. Right now, there is no way to restrict 
dictation lo numbers, or constrain the dictation search to a single 
word answer or a set of words that might be appropriate for a given 
field. Rather, right now, we’re focussing on freeing up tine keyboard 
and mouse so that the user can speak and think for prolonged 
periods in large bodies of text, tike letters, email, or other prose. Tills 
is not for typing in a choice of eleven point text! 


We make 
it easy 
to wire. 

The complete 
approach to 
whole-house video 
distribution. 

Watch every video source on every TV in 
the house. Works with DVDs, VCRs, satellite 
receivers and computer video output. 
Introducing the All-in-Two integrated system. 
This product comes 
complete with a 
multi-channel 
digital modulator 
and a coax cable 
distribution panel. 

The AII-ln-Two 
is ideal for installs 
where... 

• The modulator needs to be located 
separately from the distribution panel 

• Up to four modulators are needed 

• Up to eight TV outputs are needed 

• Future upgrades may be needed 



Test Drive 

Bring lip your application, start ViaVoice direct dictation 
services, activate the dictation system with the phrase "Ixgin 
direct dictation", and then, when the system is ready, click in a 
text field of your application, and dictate the phrase “Please 
write to Mr. Wright right away [periodl". Alter a couple seconds, 
you should see the text appear. If there are no errors, say 
"correct mister", and "Mr." will hilitc, and the correction window 
will open wit It alternatives, as in Figure 6. 


Models available: 

3425 Dual Digital Modulator & 

3445 Quadruple Digital Modulator 

Two and Four video inputs • eight outputs 

• IR control • Input for CATV or antenna 

• FCC certified • UHF 14-65 • CATV 65-125 
(excluding channels 95-99) 



For more information cal! 800-999-5225 or visit 
www. channelplus .com 


©2000 Multiplex lect-inoiogy. Inc Broo. ca 02B31 


September 2000 • M acTecii 






























Figure 6. Correctttig in your ajtplicalion. 

Then, you can pick one of the alternatives, or say “close 
correction window”. For more things to try, consult the Via Voice 
Users Guide, 

Getting Creative 

Beyond direct dictation, there arc other tilings you can do. 
You can write AppleScripts to control your application to 
jK’rform routine operations. You could even have a "secret about 
box" phrase bring up a nice little Easter egg in your product. 
Likewise, you could have other key phrases that, rather than 
processing as text, trigger behaviors or commands. Em sua fc 
there are other things that I've not ihouglu of yet. 

Future Directions 

“Prediction is difficult, es/>edafly about the future ." 

A word about future versions. Simple extrapolation from 
Via Voice Millennium late last year to Enhanced in the middle of 
this year should suggest that the Via Voice for Mac team lias been 
busy, and continues to !>e busy, adding features, fixing bugs, 
and gening the product into our customers' hands. I cannot say 
what will result from this activity, but it is likely that developer 
opportunities, already greatly expanded with Enhanced, will 
continue to grow as the product line itself evolves and matures. 

An interesting point on this topic is that Vi a Voice is die only 
speech software technology that is currently available For and 
has an installed base on Windows, Mac OS, and several flavors 
of Linux. If you re thinking cross platform speech, litis is where 
you want to be. 

Microphone Off 

'Jtiere you have iu The amount of work you need to get 
dictation into your application varies from 'it works already lor 
free" to “l had to write a couple of Apple event handlers,” 
Beyond that, you can get as creative as you want. 

ViaVoice for Macintosh has been a best seller since its 
introduction in 1999* and with ubiquitous dictation availability in 
the latest edition, there's a good chance that many of your 
customers will have ViaVoice, and want to dictate into your 
application. Believe me, the number of comments alx>ut Td like 
to !>e able to dictate into Application X” exceeds just about any 
other feature request. Make it so! 
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Links 

* http://www, fbm.com/viavoice/ 

The main ViaVoice Web site, 

* http://developerapple.com/technotes/te/te_27.html 
Tech note IT 27 describing T5MTE functionality. 

* http://developer.apple.com/dev/techsupport/develop/issue29/griffith.html 
Great article by Tague Griffith describing TSM and TSMTE 
(including the elusive l gtxT event). 

* http://devebper.apple.com/ja/technotes/tn 10002. html 

Tech note describing gtxt' event Only if you can lead Japanese! 

* http://de veloper.a pple com/techpu bs/mac/Text/Text-409. html 

Chapter 7 of Inside Macintosh: Text the essential reference 
for TSM functions and use 

* http://www.zdnetxom/pcmag/stories/revfews/0 f 6755 f 2385302 r 00.html 

PC Magazine review of ViaVoice showing test results of 
accuracy improvement to 98%. ISO 
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You won't believe what you can do with ReplayTV. It's not a VCR, it's a digital television recorder, so you can actually pause live 
television, and do your own live instant replays, it also has a search engine, so you can punch in a keyword, say "Golf," and it 
will find and record any golf program that comes on — all without videotape. Or you can just punch in the name of your favorite 
show and let ReplayTV find it and store every episode, so you'll never miss it again. If you had ReplayTV, what would you 
do? Call us at 877-replaytv or visit www.replaytv.com 


f r } re p i 


aytv” some televisions have all the fun. 


©2000 ReplayTV, Inc. 


Available at any Tweeter Company, Best Buy and Amazon.com 






































OS X 


By A ndrew C Stone 


More or Less: Drawers and 
Disclosure Views for Cocoa 


In designing an intuitive interface for 
users, the great French architect Le 
Corbusier’s adage still rings true: less is 
more. The less user interface you have 
visible, the more likely the user will be 
able to understand your program’s feature 
set, But applications without depth and 
functionality are boring and leave the user 
feeling “if only the application could do X 
or Y”. There are several ways to hide 
complexity and still have the features 
available for expeit users* Along with the 
ubiquitous tabview, two major techniques 
are the drawer and the disclosure view. 

Mac OS X introduces the concept of 
the drawer - a Daliesque subwindow 
which expands from under the parent 
window in a smooth opening animation, 
remaining attached to the window until 
no longer needed when it animates 
smoothly closed. An example of a good 
use of drawers is Mai Lapp's 
“Mailboxes". Drawers have certain 
limitations however — for instance, you 
cannot pull out a bottom-mounted 
drawer with a depth greater than the 
height of the window since this would 
violate the physical reality being 
emulated. Moreover, there were no 
drawers in Mac OS 9 or Mac OS X 
Server, so another technique, disclosure 
views must be used. The disclosure 
view, the little blue triangle that “shows 
more* by expanding the window to 
reveal more user interface, is one 
excellent technique. You can see this 
button in the standard Save Panel - 
which expands to show the file browser 


or collapses to present a very simple save interface. In this 
article, you will learn how lo implement drawers and two 
types of disclosure views: one that expands the window to 
the right, and one that expands the window below, 

«C1 osedDrawer.tiff This window presents a simplified 
interface for the user, wills die drawer closed.» 
«ExpandedDrawer.tiff When the drawer is pulled out, 
additional options become available» 

Drawing Upon Drawers 

The drawer is an instance of the NS Drawer object, a simple 
non-visual controller type object that acts as a coordinator, 
NSDrawer has a simple application programmer's interface (API) 
which allows you to specify the parent window, the content or 
container view which gets inserted into the drawer, the 
preferred edge from which the drawer expands, methods to 
programmatically open and dose it, and a method to determine 
whether the drawer is open, dosed, opening or dosing. 
Moreover, there are optional delegate methods sent to the 
drawer’s delegate and objects which register for drawer 
notifications before and after closing and opening and before 
residing of the drawer. The full API is presented in 
/System/Library/Frameworks/AppKit.framework/Headers/NSDrawerh. 

InterfaceBuilder the application to build graphical user 
interfaces via drag and drop of components - now has two 
ways to create drawers without writing a single line of code, 
From IB's Windows Palette, you can either drag out an 
NSDrawer object, and hook up the parent and content view 
yourself, or drag out a window with the drawer window 
already attached. The first method is excellent if you are 
modifying an existing interface, and the latter when you are 
designing from scratch.«DrawersPalette.tiff: You can create 
completely functional drawers just by drag and drop from 
I nter faceBu i 1 der». 

I recommend that you create a new IB document and 
add a drawer/window combination to see how easy it is, and 
to learn a trick of the Lrade: Lhe Invisible box grouping 
technique. All visible objects in Cocoa are NS View 


Andrew Stone <andrew@stone,com> is the chief executive haqner at Stone Design Corp <http://www.stone.com/> and 
divides his lime between raising children, llamas & cane and writing applications for Mac OS X and playing with Darwin. 
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.subclasses, and they form a hierarchy that is rooted in the 
window's content view, the root enclosing view which 
contains everything in the window except the window 
controls and shadows. Because you cannot use IB to connect 
to this content view directly, you'll need to explicitly create 
a view which contains all of the user interface items that 
belong in the drawer. Select all the items and choose Layout 
-> Group in Box. Bring up the inspector, and choose the 
Attributes pop-up menu item. Click on “No Title" and the no 
border icon - now you have an invisible containing view, if 
you click on the smaller drawer window created when you 
added the drawer/wintlow combination, you see just such an 
invisible NSBox. Be sure to add your drawer components 
inside of this box by double-clicking it before dragging on 
new user interface elements. 

interface Builder allows you to specify the preferred edge 
from which the drawer should expand with the NSDrawer 
Inspector's Attributes sub-panel For full control of the 
drawer’s appearance and position, you may have to actually 
write a few lines of code, because some functionality is not yet 
fully exposed in Interface Builder. As of DPi, you need to set 
the drawer's delegate and size constraints programmatically. 
You can control the maximum and minimum size of the 
drawer, as well as the leading and trailing offsets. On a side 
mounted window, live leading offset is the height difference 
between the top of the drawer, and the top of the parent 
window's content view. Likewise, the trailing offset is the 
difference between the bottom of die drawer and the bottom 
of die parent window. All of the size constraints are mostly 
hints because there may be conflicting parameters. 

Now that the drawer is configured, all that is required is to 
provide the user a means of opening and closing it, You need to 
have a button on the main window' or a menu item which will 
expand the drawer when closed, and dose it when open, 
simultaneously adjusting die text and/or Icon on the button to 
synchronize with the drawer's state. Because the drawer can lx: 
in the act of opening or closing, you might want your button to 
do something only if it is actually dosed or open, and just ignore 
dicks if the drawer is still animating between the open and 
dosed state. 

// given an instance variable "drawer" for the NSDrawer and the sender is the button: 

* (void)openGrCloEeDraver; [id)sender I 

if ([drawer state] “ NSDrawerClosedSLate) I 

// tell the drawer to begin the opening animation: 

1drawe r op en:s end erf: 

// remember, not everyone speaks English! Code inLcmalkmally 

[sender set?i11n:HSLoc alized S t ringF romTab1e(@ M Lea s 
Options*,#"CoolApp"of drawer open and close button 
when the drawer is open")]: 

[sender set linage: [NSImage ImagcNatned:#"OpenDrawer"]: 

\ else if [[drawer state] “ NSDrawerOpenSt ate) | 

[drawer close:sender]; 

[send e r se tilt1e;NSLoca1lied Stringfr gnTab1e(<T More 
Options"*#"CoolApp",#"title of drawer open and close button 
when the drawer is closed**)!; 

[sender setImage:[NSImage imageNaned:#"CIoseDrawer"]: 

I 

ff if it's in an opening or dosing state, we ll ignore the dick 
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As for initializing the drawer, you might wunL Lo do some of 
the following in the method that gets called by any object in an 
Ill nib file after all the outlets are initialized, awakd-’romNib: 

- (voidjavakeFrnnNIb 
i 

[drawer sctLeadingOffset;10-]: 

[drawer setTrailiug£)ffset: 40 .] : 

[drawer setContentSiEe:IrightBox frame] , sizel; 

[drawer close:seifh 
[drawer setDelegate:self]j 

Secret Disclosures 

When a drawer is inappropriate because of size, 
backwards compatibility, or design issues, the classic 
disclosure view comes in handy. When disclosing 
additional user interface elements, the programmer is 
responsible for resizing the window and making sure 
everything fits correctly. All of this can be done easily 
using the technique of the invisible box as the top 
level container of the items in the standard window, 
and another invisible box as the top level container of 
the additional items which are presented when the 
window is expanded. The two most typical 
configurations are windows which expand to the right, 
and windows which expand below. We'll look at Lite 
expand to the right case first since it is simpler, 
because it does not involve moving the origin ol the 
window. The underlying window display mechanism 
in the AppKii wall automatically handle the cases 
where expanding the window would place part of the 
window off screen. 

To understand the automatic resizing behavior of 
views (autosizing), it is helpful to look at 
Interface Builder's Autosizing interface element of the Size 
Inspector. Each of the 6 possible stretch I behaviors are 
represented graphically with rods and springs. A rod 
means “leave this dimension static* and a spring means 
"let this dimension fluctuate with the changing size of the 
window*, «StretcliThcObject.tiff In this case, the object 
stretches and shrinks to fit into its containing view» 
«LcavcObjec*tRel:itiveToLowerKighi.tiff 1 lere, the object 
will remain in relative position to the lower right of its 
containing view.» 

Of course, you can set these all programmatically using 
NS View's -setAuUxsizing:(inDmask method by or'ing together the 
vertical and horizontal stretching behaviors: 
NSViewNotSizahle, NSViewMinXMargin, NSViewWidtliSizahlc, 
NSViewMaxXMargin. NSVjewMinY Margin, NS View! feightSizable 
and NSViewMaxY Margin. 

Usually, you want the main items in the window to 
be resized when the user resizes the window - for 
example, a scrollable text view. In order that the 
disclosure view maintains the correct size whether it’s 
showing or not, well approach the problem by always 
leaving the extra box in the window. When the extra 


box is hidden, the window will dip the box, when it’s 
revealed, the window will be resized to contain it. This 
solves two problems: one, the extra items will be 
correctly freed when the window is released regardless 
of whether the extra items are showing, and two, the 
extra items will he correctly resized when the window 
is resized, even if they are not ctirrenily exposed. 

In the following example, we have sulxriassed 
NSWindowCon[roller and placed the logic of resizing in 
the subclass controller. In IntcrfaceBuilder, the autosizing 
of the elements has been established, and we honor 
these sellings by noting them at the beginning, and 
resetting them after resizing the window. 

The button is set to be a two state "toggle* button, 
and we assign the images inside InterfaceBuilder in the 
Icon and Alternate Icon fields. By changing the state of 
the burton, the Icon automatically changes. This works 
with text as well by assigning an alternate title to the 
button, however, a down facing triangle image when 
the window is collapsed but can be expanded 
downward and an upward facing triangle image when 
it is expanded but can be collapsed works well. 

// given: the controls to be displayed when [he window expands art all inside 
// an invisible- NSBox named righilkix The main Conuol.% arc all inside a Ixix named 
// left Rost . The two boxes art laid out side by side in Ulc window to fill the window's 
// content View, Inside the lefi box, near the upper riglit is the two-state button whose 
// target is the window controller with ihc action nit ireOrlcssToThellight Action:. 

(void) mo reOrLcsstoTheR 3 gh t Ac t ion: [ id) ste ride r 

NSWindnw *win " [eelf window]: 

NSReet wltiFrame - [win frame] : 

NSRcci eightFrame ® [rightbox icame I: 

// get I he original sellings for reestablishing later: 

1 ttt leftttask = [leftBox ant or el1 1 ingMask]; 

Int rightMask = [rightBox auLoreslEingHask]; 

// toggle the State 

int stateToSet = 1 [sender tag] r 

ft set the boxes to not automatically resize wIh.ii the window resizes: 

[leftflox setAutoresiaingHaskiNSViewWotSienhle]; 

[ri&hrBox setAntoresis:ingHaE:k;NSVlnwHot S l zahlel: 

// if ihe button's state is t. then stateToSct -- U. let s collapse-; 

if {stateToSet ” 0) 3 
// reduce the desired size by the width of ihe right box: 

wlnFrame.sixe.width ^ NSWidthCrightFraniE!): 

3 else I 

// increase the desired width by the width of ihe right box: 
winFrame.size, width 1“ NStfidth(rightFrame); 


ft change the Mate of the button 

|sender setStateistaLotoSetJ: 

[sender sctTagratuteToSetJ; 

// resize the window and display: 

[win setFrametwinFraaie display:YES]; 

ff reset the boxes to their original aufoM/r masks: 

[leftBox setAutoresialngHaskrief Utaskl; 
[righr.Box scLAuiorcsiziiigMask: rightMask] ; 
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Another way to sell software 


Mind Vision Software, creator of Installer VISE, introduces eSellerate, the quick and easy way to 
speed up your online sales. Designed especially for developers like you, eSellerate puts instant 
gratification into the hands of your customers. How, your application can sell itself with no 
manual intervention from you. Hone, nothing. Huda. W W W. 6 S © i i e \ 0 1 6 • 0 6 t 



Adding n disclosure view which expands the window 
below is slightly more tricky because well have to move the 
origin of the window as we increase or decrease the height 
of the window so that the window keeps the title bar in the 
same location. Moreover* since origins begin at the bottom 
and move to positive Y upwards, we ll have to move Lhe 
origins of the boxes as well. 

- UBActionJfflQreOrLenERownAcT iors: (id)semler l 
NSWindow *win - [self wlndaw]: 

NSRect wlnFramt? ~ fvfifi frame] ; 

// well need ro know the size of both boxes in Uiis ease: 

NSRecl topFrame - [tripBox frame]; 

NSRect bottomFrame * [bottomBox frame]: 

// gel live uriginaJ sellings for reestablish iftg later 

int topMask = ftopBox .mtoresizingMaskl: 
tnt bottomMask ■ [hot tomBox autoresizingHaskl; 

// toggle the suit* 

hit stateToSet m 1 - [sender tag] ; 

// set the boxes lo not automatically resize when the window resizes 
[topBox setAutoresi7ingHssk:HSViewNatSi2abie]: 

[bottomBox setAutore?: iz I n^Mask: NSViewNctSizable] ; 

// if ilie button's state is 1, then staieToSet = l), collapse it: 
if (statoToSet =03 f 
// adjust the desired height and origin of the window 

winFraroe. size. height - NSHeight (boi lumFrame); 
winF cause.origin♦y + = NSHei gh t ( hi> ■ 1 omFrame; : 

// adjust tile origin of the bottom box well below the window 

boztomFrane* orfg1n«y NSHeightIbottomFrawe3; 

// begin the top box :u the bottom of the window 
topFraJnc.origin.y * 0,0; 


1 else t 

// stack the boxes one on top of the other 

bottomFrame,origin./ - 0.0; 

tepFraue* origin*/ ■ MSHeighi (hatLyaiFrame); 

// adjust the desired height and origin of the window: 

winFrame.size.height += WSHeighttbottoaFcame}: 
w \ nFrame.origin,y -- NSHeight(bottom?rane]; 

I 

// adjust locations of the boxes: 

[topBox setFrarae:topFramel; 

[bottomBox set Frame: hot toraFr ante]: 

// change the state of the burton to reflect new arrangement: 

[ sender setSta te : staleToSet]: 

[sender setTagtsiate'lobetJ : 

// resize the window and display; 

[win setFrame:winFrame disp]ay:YF,S]; 

// reset ilie boxes to their original anmsize masks 

[topBox setAutoreslzIngMask:lopMask]: 
ibottomBox setAutoresizingMaskibottomMaskl; 


Conclusion 

With drawers and disclosure views, you have the tools 
and techniques to present simple and elegant interfaces, with 
more features available at the click of a button. 
Interface Builder can provide almost all of the support 
necessary to fully implement drawers, and with just a few 
lines of code, your applications can take advantage of the 
powerful new features of Cocoa. 
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Sharon Monplaisir, Olympic fencer and entrepreneur, 
registered her domain name to put her business online 
at register-com. Visit us at wwwuegister.com or call us 
at 1-800-7-WWW-NET, an5 well help you register your 
domain name right over the phone. 
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PROGRAMMER'S 

CHALLENGE 


by Bob Boonstra , West/orcl MA 


Busy Beavers 

Before we get to this month's Challenge, l have to confess 
being a tittle distracted. No, not because the annual holiday up 
at the lake is just a few days away, although Ill also confess that 
the prospect of a couple of weeks away from the Real Job is 
most appealing. No t the distraction is l>ecausc UPS just delivered 
another addition to the family of computers at the Roonsim 
household. Tlie most recent additions have been [Macs for the 
Junior members of the family, but this one is for Me. A new G4. 
No, not one of the new dual-processor models introduced by 
Apple at JaviLsWorld. (Those of us in Boston cannot 
acknowledge use of the term MacWorld for anything on the 
Right Coast that doesn’t happen in Bean Town.) Dual processors 
might mean something to those Photoshop users among you, 
but they don't do much for the Rest of I is until Mac OS X comes 
along. No, the new addition is one of those now-obsolete single- 
processor G i-500 models that have (finally) dropped a little in 
price. As those of you who participate in the Challenge contests 
know, fVe been limping along with an old 8500, enhanced over 
the years with a faster 604e, then a dual 604e upgrade (BeOS, 
oh BeOS, wherefore an thou BeOS?), and finally with a G3 
hoard. Several readers have asked in the past about whether 
AltiVcc technology could lx 1 used in the Challenge, but, sadly, I 
didn't have a G4 to use in the evaluation, A problem now 
rectified, or at least it will be once 1 complete the file transfers 
proceeding even as I write. 

Now that you all know about my new toy, we can gel on 
to the business at hand. This month’s problem was suggested by 
F. C Kuechmann, who earns two Challenge points for rhe 
suggestion. Your Challenge this month is to create a Busy Beaver 
Turing Machine and write a program that simulates its execution. 

The Busy Beaver problem was invented in the early 1960s 
by Ttbor Rado of Ohio State University, He asked the following 
question about 2-symbol Turing machines: what is the largest 
number of Is that a Turing machine with n states could write to 
a tape initially filled with Os, That ' busy beaver" number, or 
BfKn), has some interesting properties. For example, by 
reasoning about the Halting Problem, one on show that BB(n) 
grows faster than any computable sequence. 

An internet search shows that the Busy Beaver problem 
continues to attract interest. Until 1985, I lie largest value for 
a 5-state busy beaver produced 501 Is, Then George Thing 
found a 5-state machine that produced 1915 Is before 
halting. And in 1987, Ileiner Marxen (and Jurgen Btratroek 
showed that BB(5) is at least 4098. 


For reference, you can start wiLli die following URLs: 

Marxen s page at < htto://www.drbjnsel.de/-hemer/BB/index.html >. and 

< http://graiLcba.c5uahio.edu/-somos/bb.html > 

The prototype for the code you should write is: 

typed ef unsigned long along; 

typedef enttm tkHoveLrfr- l,kllaH=0. kMoveRight^iI HoveDin 

typedef struct TMRuie I f Turing Mndiiirc rule 7 

u 1 ong Ids c a i e: P this rule applies when ihv machine slate is okCtaic V 

K hj can inputSymbo J : f* and the current input symbol is InputSymbol 7 
along newState: P sel current state to newState when this rule fires 7 

Boolean out put Symbol: P write mitputSymhol to tape when this rale fires 7 
char moveDi rection; f* k Move I eft, kMoveRighc.or kl LiIe 7 

1 TMRule: 

along p return number Of rules 7 BusyBeaver5 { 

TfflUile i-heTMRiilea U, 

P prenlhxiJtcd storage, return the rules tor your BB machine 7 


Boolean P return true for success ■/ RunT ut inggach im ( 

TMRule theTMRulefd], 

r preal located storage, return I he rules Tor your 111! machine 7 
along nuiftborOflUKules, 

P the number of rules in thcTMKuks 7 
ulong mrnByt es XnHa 1 fTape. 

P half size of the ‘InfinitcTuring Machine tape 7 
unsigned char *ttaTape. 

r pointer to prcaJlocated Turing Machine tape siurage 7 
f Eidi byte contains B rape symbols, cadi symbol is 0 or 1.7 
P The tape extends Burn mffapcl -flumUyU'sLnl lain ape] tit 

unTapc|nomBytestnHainhpe^] 7 
TTape position <1 is <unTap*|<l| & OxBtl), 
tape position I is (iiulkpefftj & 0x40) 
tape position I is (UnTapeH J & 0x01), etc. 7 
ulong ^nuiaberOfleGenerated* 

P return the number ol Is placed on the tape 7 
ulong * numb e rOfK u l fsKkpc tiled 

F return the number of rules executed when running BB. including the lca.lt rule 7 

): 

The first thing you need u> do is to seleci the 5-state Busy 
Beaver Turing Machine that you will simulate in your 
RunTuringMachine routine. Since scoring is based on how busy 
your beaver is, that is, on how many Is it produces on the 
simulated 'luring Machine tape, you want to give some careful 
ihougiu u> this selection. This l uring Machine should returned by 
your BusyBeaverS using the TMRule data structure. BusyBeaverS 
may return a hard-coded Turing Machine: ii does not need to 
identify l he busy beaver at run time. 

My test code will then provide the output of BusyBeaverS to 
your RunTuringMachine routine, which should simulate the 
execution of the input 'luring Machine. RunTuringMachine will be 
provided with a blank (zero-filled) tape TmTape that is 
2*numByteslni lalfTape in size. The "read head" of the Turing 
Machine is initially positioned over position |0] of the tape. On 
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exit, tmTape should contain the output of the Turing Machine 
Ixring simulated. In addition, you should return in the 
appropriate output parameters the number of is on the output 
mpe and the number of slate transitions that occurred during 
your execution of the Turing Machine. RunTuringMachine should 
return TRUE if it was able to successfully execute the Turing 
Machine, and FALSE if it failed for some reason, such as running 
out of simulated tape, (ii is not my intention to provide a 
simulated tape that is too short, but your code should fail 
gracefully if that happens during resting.) 

RunTuringMachine must provide a general Turing Machine 
simulation, not dependent on the Busy Beaver problem or on 
the content of the initial input tape, I may choose to verify 
correctness of your RunTuringMachine code against other input 
Insides that produced by BusyBeaverS. 

The winner will be the solution that identifies the >suite 
Busy Beaver generating the most Is on lilt output tape. Among 
solutions with equal numbers of Is. the solution that produces 
the output in the fewest number of Turing Machine steps will be 
the winner. And, for solutions that produce the same output in 
the same riuinlxfr of steps, the winner will lx the solution that 
executes the Turing Machine in the least execution rime. While 
my hope is that one of you might break new ground in the field 
of busy beaver research, my expectation is that the winning 
solution will be determined by the execution time criterion. 

This will lx, 1 a native PowerPC Challenge, using Lite 
Code Warrior Pro S environment. Solutions may lie axled in C, 
C++, or Pascal, As is our tradition for the September Column, 
well also allow solutions that are completely or partially coded 
in assembly language. And, yes, this time you can take 
advantage of the AltiVec features of the G4, 

TiiRtii Months Ago Winnuk 

Congratulations to Willeke ilieken (T he Netherlands) for 

submitting the winning solution to the June Rub # k Rotation 
Programmer’s Challenge. Readers may recall that the R\ib*k 
Rotation Challenge required contestants to display an image of 
the famous puzzle and respond to commands to rotate the entire 
culx 1 or indiv idual cube faces. Scoring was based on correctness 
of the solution, in this case the smoothness of the displayed 
rotations, and on execution time. 

The fact dial Willeke was the only person to submit an entry 
does not detract from his solution in the slightest, although it did 
significantly increase his chances of wanning, (You ain’t win if you 
don't play!) Willeke elected to use QuickDraw3D to implement his 
solution, motivated by a desire to gain some experience with the 
QD3D API. His axle creates 26 individual cubes (the center cubic 
is never visible) using die AddCubie routine. Although it might kxrk 
like a lot of work to set up the cube, the effort pays off in the 
simplicity with which one can rotate the cube (RoiateCube), turn a 
face oh he culx (QuarlerTurn), and draw die entire cube (DrawCube). 
regardless of orientation. 

With only one entry, 111 omit the usual table describing the 
parameters of the solution, and simply observe that tills victory 
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Mac ienlopCrS everywhere have a 
major need for CARBON and 0©^©^ 
application porting, ,\ e J user interface 
implementation, and OllillEil development 
services. Toward that end, several 
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With the experienced 
Mac OS development team 


Red Rock Software specializes in the Macintosh software devel¬ 
opment. Red Rock Software's team of senior engineers aver¬ 
ages over 10 years of development experience on the 
Macintosh platform. Our expertise and experience has gained 
us the trust of companies like Apple Computer, Iomega 
Corporation and Sorenson Media. 

If you are looking to get your product compatible with Mac 
OS X quickly and with extreme quality, let our experts help. 

• Aqua Interface Implementation 

• OS X Carbon Porting 

• OS X Native Cocoa Application Development 


R E D0O C I 

software 

call Red Rock at 888.689.3038 
or visit us online at www.redrocksw.c 



OS X Development 




Ready to take 
the plunge? 


Okay, everyone into the Aqua! 
What? Can't swim? No problem. 
Just climb on our back* We’ve been 
to the bottom of Apple's new Mac 
OS X f far beneath its cool Aqua 
interface. Porting to Carbon. Diving 
Into Cocoa. Firing up Power Plant, 
And developing KEXTs, NKEs, and 
I OKU drivers. If you're working on 
an OS X project, we can support 
you at every level. 


A deep pool of talent 

We founded our firm on the Mae 
a decade ago. It's in our DNA. Which 
is why clicnls such as 3dfx, Apple, 
and Lexmark come to us for 
assistance. We specialize in full-service 
commercial software development and 
we thrive on challenging projects. 

The ones that make your head spin 
and your staff suck for air. 


Contact us soon. Well help you 
make a splash in the market 
—cannonball size* 


Critical 



711 SW Alder Street, 4th Floor, Portland, OR 97205 503.222.2922, www.criticalpath.ami 

Portland • San Diego • Tokyo 
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ShadeTree 


415.491.220( 
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Robosoft Technologies 

www.robosoftin.com 03 ft D G TS 

v j n product 
development 

Indian mind power@ , , 

an unbeatable price 


arbon Porting 
qua Implementation 
indows to Mac Porting 

rial discounts for ADC members 


Robosoft is an India based specialist in Mac product 
development, Windows to Mac porting, Carbon porting 
and Aqua implementation. Our engineers have a strong 
product development experience with a thorough 
knowledge of C/C++, Java,Mac OS Toolbox, 
Macsbug, QuickTime, Carbon API and PowerPlant 
Application Framework. 

We have a proven track record for product 
development out sourcing and delivering the 
projects on time. Our clients include a veritable 
who's who in the industry - Apple, Adobe, 
Quark, FileWave, Versaware, Veon, NetJumper, 
CEI, The Anderson Group and eCapital, among 
f others. To know us better, visit our website 
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Since 1991, high tech companies like Apple Computer, 
Hewlett Packard, and Leica Microscopy have turned to 
Art & Logic for assistance in implementing cutting 
edge technologies. 


Now, with the advent of OS X, Art & Logic is helping 
companies make their products compatible with 
Apple’s new operating system. Art & Logic engineers 
are industry leaders in Carbon & Cocoa porting, Aqua 
implementation, and driver development. 

In the new economy, where time to market is every¬ 
thing, you need results. Art & Logic delivers. 



Art & Logic, Inc. 

www.artlogic.com 
877-278-5644 (toll free) 
info@artlogic.com 


The software engineering company that helps bring your 
hardware product to market—guaranteed 














_ Eat your vegetables. 

Exercise every day. 
SJ Port to Mac OS X. 

□ Call your mom. 


All of these are good for you. 
We can make one of them easy. 


Since 1989, The Omni Group has worked with the technologies that have been refined into Mac OS X. 

Moving to Mac OS X is a big step for your company, and you need consultants who can help you both 
plan how best to make the transition and follow whatever path you choose. 

That’s been our business for years. No matter what kind of product you have, we can get it up under 
OS X, fast: 

* Real games: We ported id's Doom and Qpake games to NEXTSTEP and OS X. Quake 2 took us a week. 

* Big apps: We ported .Adobe's Frame Maker to NEXTSTEP and Sun's Concurrence to OpenStep/Solaris. 

* Big libraries: We ported the Oracle 8 client libraries which Apple ships today in OS X Server. 

* Serious drivers: We ported Sdfx's Glide and wrote Voodoo2 and Rendition drivers for OS X Server. 

We've written new mouse drivers for OS X Server and joystick drivers for OpenStep. 

* New apps: We wrote GmniWeb, the only native OS X web browser* and OmniPDF, the native Acrobat 

viewer for OS X. 

Mac OS X is what we do. Let us help you do it, too. 


The Omni Group 




2707 Northeast Blakeley Street 
Seattle, Washington 98105-3118 
www.omnigroup.com/consuking 


sales?omnigroup.com 
800.3 lS.OMNi x201 
206.523.4152x201 


for OSX, NlXtSTEP* and (fpenSlcrp are trademark* qj Apple* Acrobat tlml I'ftunir Maker are tradentiil* o| Adrift,- Nvxtctm, bit (ftiakt: *tnd Eftm are i rude marl x ol k| S-lmam Soldi* dm! Concurrence an: trademarks 
of Sun Mk jTJxyvtcmv Unufe n a trademark u| Gmde, Clide and Vomb*. are tradcittifta >4 SdfK * I 1w Omni Omp" OmnAVcb, OmtrtPDf, and the < inuif Gem bMp urv our*, Ite don't *ue ul Ami call c our mom 









Get the power and experience you need fron 
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engineering, inc 




• • • • 

With over thirteen years in providing 

programming service to the Mac community. 
Prosoft is committed in delivering the ultimate 
quality software products and service. 


Our Engineers have extensive knowledge in: 


Macintosh PPC Drivers, 
Shims and Extensions 

Macintosh Power Plant 
Applications, Mac OS X 
applications and drivers 

Carbon application 
porting for Mac OS X 

Multimedia and QuickTime 
Applications 
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and Linux Drivers 
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vaults Willeke into 4 th place in the overall Challenge standings. And 
remember, you ain't win If you don't.... } uh, I'm repeating myself. 

Top Contestants 

Listed here a a* the Top Contestants for the Programmer’s 
Challenge, including everyone who has accumulated 10 or more 
[x lints during ibe past two years, Hie numbers below include 
points awarded over the 2A most recent contests, including 
points earned by this month's entrants. 


Rank 

Name Points 

Rank 

Name Points 

1, 

Munter, Ernst 

245 

10* 

Downs, Andrew 

12 

2. 

Saxton, Tom 

126 

11. 

Jones, Dennis 

12 

3. 

Maurer, Sebastian 

78 

12. 

Day, Mark 

10 

4~ 

Rieken, Willeke 

65 

13. 

Duga. Brady 

10 

5. 

Boring, Randy 

50 

~ 14.' 

Fazekas, Miklos 

10 

6. 

Shearer. Hob 

47 

15. 

Murphy, ACC 

10 

7. ' 

Taylor, Jonathan 

26 

16. 

Sdengut, Jared 

10 

8, 

Brown, Pal 

20 

17. 

Strout, Joe 

10 

9. 

Hcilhcocfc, JG 

16 





There are three ways to earn points: (1) scoring in the top 
5 of any Challenge, (2) being the first person to find a bug in a 
published winning solution or, (3) being the first person to 
suggest a Challenge that t use, 'fhe points you am win are: 


1st place 

20 points 

2nd place 

10 points 

3rd place 

7 points 

4th place 

4 [xrinLs 

5th place 

2 points 

finding bug 

2 points 

suggesting Challenge 

2 points 


Here is Willeke’s winning Rub*k Rotation solution: 

KuhikKotationx 
Copyright © 2000 
Willeke Rieken 

r 

draws (a simplified version of) Rubik’s cuhe and animates 
rotations of the cube ami of (hr faces of the cube, 
l'm using QDM) because I never used it ami it seemed 
more fun than a diy method and drowning in sin and cos 
anti r still think it is 

the model object for the cube consists of 26 group Ejects 
for cadi cubic and a rotation object the rotation object 
contains ail previous rotations of the whole cube added together, 
cadi cubic object contains a box object and a rotation object, 
a cubic rotation object contains all previous rotations of the 
cubic that was caused by rotating a face of the cube 

during rotation of the cube an extra rotation object is 
submitted after the rotation the rotation object of die tube 
is adjusted. 

during rotation of a fate an exu rotation object j.s added to 
every cubic in die face, after die rotation the extra rotation 
object b removed and the rtrtatktn object of the cubic is adjusted 

references to the rotation object of the cube: and to the cubic objects 


are kept in glotxds. 

7 

#Include <QD3D.h> 

# Includ<? <QD3DDrawContext. 

^include (QB3BRenderer + h> 

#inciud e <QD3 DShader.h > 

^include <QD3DCamera.h> 

//include <QD3PUghah> 
ff inc Ind 6 < QDBDGeomet ry. h ) 

//include (QDBBGroup.hS 
//include <qn3f)Maih .h> 

//Include <QiJ3t)Transfooii.h> 

//include <qD3DViev.h> 

//include <qD3DAcceleration.h> 

//include <qD3DErrors,h> 

//include "RubikRotatian.h" 

TQBVlewObject gVicw; // the view for the scene 
TQ3S Ly 1 eObjeci glut erpolation: 

If interpolation style used w hen rendering 
TQBStyleGbject gBarkFacing: 

If whether to draw shapes that face away from the camera 
TQ3Style0bject gFiliStyie; 

// whether drawn as solid filled object or decomposed to components 
TQBGroupObject gCubeHodel; // the cube 
TQBGroupflbj ect gCubies E 3}[3][31: 

// the cnbies 

TQBTransformGbjeet gCubeRotation; 

II cumulation of every rotation of the whole cube until tiow 
TQ BTran s f o nnOb j e c t gTemp Cu b eRotat 1 on: 

If used during rotation of the cube 
float gStepSize; 

static TU3DrawConrextObject MyNewnrawContcxi. iCWindowPtr 
theWindov) 
ff create context 
( 

TOOrawContextData rayDrawContextData: 

TQBtfacDcavContextBata rayHacDrawContextData; 

TQBCoiorARGB clearColcr: 

TGBDrsvContextObject myDrawContext ; 

II Set the background color 

clnarColor.a = 1 , 0 : 
clearColor,r = 1,0: 
clearCoIor.g = 1.0: 
clearColor.b = 1.0: 

// 111! in draw context data 

myDrawContextData.clearlniageHethnd - kQlClearHethodWi diColor: 
myDrawContextData.clearlmageCoIor ” cloarColor: 
myDravContextt)ata,panc£tate - kQBFnlse: 
myD rawCo n t extDa t a.ma sk Slate = kQ3Pa1 »e; 
myDrawContexLData.doubleBufferState “ kQBTrue; 
myMaei)ratfContextPata,drawContextData - myDrawContextData: 
rayMaeDrawContextData,window “ theWindow; 
inyHacDrawContextData.library - kQ3Hac2DLibraryNone: 
myMacDrawContextOata.vievPort = 0; 
myHaeDrawContextData.grafPort = 0: 

II Create draw context 

EnyDrawGontext - G3l%cDrawCortlext J^w{&inyMueDravGontextData) ; 
return myDrawContext ; 


static TQBCameraObject MyNewOrthographicCatnarafGWindowPtt 
theVindov, short cubeWidth) 

II create orthographic camera 

I 

TQBOcthGgraphicCarae raData orthograph I cDa ta; 

TQ3 Gamer a 0b j net c ame ra: 

T03Poinl3D from = 10.0. 1*5* /.Oh 
TQ3PointBD to - {0,0, 0.0, 0.01: 

'TOVector30 up - {0.0. 1.0, 0,01; 

orthographicOata.cameraData.placement.cameraLocation - from; 
orthographicData.cameraOata.placement.pointOfInterest to; 
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orthographieData.cameraData - placement-earneraLueution * 
from; 

orthographicData.cameraData.placement.paiuttf fluterest = to: 
nrrhopraphicData.cameraData.placement.upVector - up: 
or IhographirData.eameraData, range thither = 1*0; 
urihogr njih irDnl a * camera Data. range, yan - 1000.0: 
onhographicUa La. eaincraDaia. viewport .origin.* = -1.0: 
orihographicUala.caneroDala-v IcwPort .origin. y ~ 1,0: 
orthographicllat a . camera Data, viewport. width - 2.0: 
orthGgraphicDaia.cameraData,viewport.height * 2.0; 

// calculate view plane, size of dir cube is in QDiFoints 

orthographicData.left = -1.5 * 

( ( f1oat)(theW1ndow->portRect.right - 
rheV inflow >portRett.left)) f 
(float)(cubeWldth + I); 
orthogtaphid)eta,lop = orlhographf cDats.left ; 
orthographicData.right - ■ orthographicData.left: 
orthographicData.bottom - orthographicData.right: 

camera = Q30rthogiaphicCamera_New{6iorthographicData); 
return camera: 


static TQ3CaaeraObject MyNcwVlowPlaneCamoratCWlndowPt r 
theWindoWp short cubeWidth) 

I 

// create perspective camera 

TQ3ViewPlaneCameraData viewPlaneData: 

TQlCaneraObject camera: 

TQ3PoJnT3D from - 10.0, 0.0. 7.0i: 

TG3Foint3D to" 10.0, 0.0, 1.51; 

TQ3Vector30 up ■ 10.0, 1.0. 0,01: 

viewPlaneData.cameraData.placement.cameraLocation * from: 
viewPlaneData,came raData♦placement.pointOfInterest - to; 
viewPlaneData,cameraData,placement.upVector * up: 
v 1 euPlaneDat.a,cameraData.range.hither - 1.0: 
viewPlaneData,eameraDsta.range. yon - 1000.0; 
viewPlaneBaLa,camoraOala.vlewPort,Origin,x w 1.0: 
viewlMaijfiData.caifieraOata, viewport .origin,y - 1,0: 
viewPlaneOata.cametaOnta.viewport.width = 2.0; 
viewPlaneData.cameraBats.viewPort.height * 2,0; 

// calculate view plane, size of the cube is 5.0 in QD3Pomls 
viewPlaneData.viewPlane = 5.5; 
vlcwPlaneOata.halfWidthAtViewPlane - 1,5 * 

((float) (tbcWindov >portRoci .right 

theWludow >poitRect ,left)) / 

(float KeubeWidth +1); 
viewPlaneData.halfHeightAtViewPlane = 
viewplaneDat a,ha1ttf idt hAt VievFlane; 
viewPlaneData.centerXOnViewPiane - 0.0; 
viewPlaneData.centerYOnVievPlane - 0,0: 

ca tnu r*t * Q3 VI owP 1 a neCa imp r a_Ne w [ k v i ewP1 a neDat a); 
return camera: 


static TQlCroupObject MyNewAmbientanlyLightsi) 

I 

TQIGroupGbject myLi&htLiet: 

TQ.1 Lightest a ray Li gh t Da t a; 

TQ3 U ght.0bjee t myAmbian tU ght; 

TQlColorRGB whlteLight = 11.0. 1.0, 1.01: 

// Scl up light il.it.I for ambient light 

myLightData,isOn = kq3True; 
myLIghtData.color - vhiteLight: 

// Create ambient light. 

myLIghtData.brightness = 1.0; 

nyAmblentLight - Q3AmbientLight New(fcrayLightData): 

// Ctvaie light gmup and add each of the lights into the group. 
nyLightList " d3LigfrtGroupJfew(); 
010roup_Add0bject(myLightList f nyAmbientLighT); 
Q30bjeet J>ispose (myAiabientLight) ; 
return myLightList: 


static TOlGroupObject MyNewLightsf) 

l 

TQ3Gioup0bjeci myLightLisl: 

TQ3L i ght Data my Li ght Da t a: 

TQIPointLightData myPointLightData; 

TQ 3 Dir ectiouaiLigh tData myDir e c tio nalLigh t Da t a; 

T03L1 ght Object myAmbientLight, myPointUght. myFiliLight: 
T03Point3D pointLocation - (-10.0, 0.0, 10.01: 

TQ3Vector3D fillDirection - 110,0, 0.0, 10.01: 

TQ3Co1 or RGB wh i teLi ght - (1.0, 1.0, i.Ol; 

// Scl up light dal a for ambient light 
// I his light dim will lx- used for point and fill light also 
myLightData,isOn * kOJTrue: 
rayLightData.color - vbiteLight: 

// Create ambient light. 

myLl ght Data .brightness = 0.25; 

myAmbientLight - Q3 Ambient Light_New{ Amy LightHata); 

// Create point light 

myLightEata.brightness = 1.0; 

myPointLigbtData,lightData = myLightData; 

myPointLightData.castsShadows ** kQlFalse; 

myPeintLightData.attenuation ** kQ3AttenuationTypeNone; 

myPointLightDate.location = pointLocatlon: 

myPointLight - Q3PointUght New(ArayPointLightData); 

// Create fill fight. 

myLightData.brightness = 0.2; 
my DirectionalLightData,lightData “ myLightData; 
myDirectionalLightData.caetsShadows = kQlfalse: 
myDirectionalLightData.direction * fillDirection; 
myFlllLlght “ 

Q3D1rec LionalLIght_New(&myDirect tonal 1.1ghrData); 

// Create lighi group and add each of the lights into the group. 

myLightList = Q3LightGroup_New(): 

Q3Group_Add0bject(myLightList. myAmbientLight); 
Q3Gioup_AddObjset(myLightList H myPointLight); 

QIGrnup AddObject(myLightList, myFiliLight); 

Q30bj ec t_Dispose(myAmbientLight): 

Q30bject_Dispose(myPo1ntUgh 11: 

Cpobject_Dispose(myFiliLight); 

return myLightList; 


static TQ3ViewObject MyNewViewfCWindowPtr theWindow, short 

euMidth) 

I 

TQlViewObject myView; 

TQjDrawConteirtObject myDrawContext : 

TQIRendererObject myRenderer; 

TQ3Camera0bject myGamera: 

TQIGroupObfeet myLights: 

myView “ QBView Kew(); 

// Create and set (tow context 

myDrawContext - KyNewDruwContcxl(thoWIndow); 
qiView_SetDrawContext(myView, myDrawCimtexi); 

Q30bject_Dispose(myDrawContext) : 

// Create and set rendtrer. 

// use the interactive software rvndcrvr 

myRenderer = 

Q3Rondcre r_NewFrOH»Type(kQIHende rerTypelnteractive); 
Q3View_SetKenderer (my View, myRctiderc r) : 

// these lwo lines set us up to use the best possiWc rendered 
// including hardware if it is instilled 

Q3InteractiveRenderer_SeiDoubleBufferBypassImyKeuderer. 
kQ3Ttue); 

QllnteractiveRenderer SetPreferences{ my Render e r. 
kQAVendor_BestChoice, 0): 

t for software reoderer. without hardware accdleratmn, replace with: 

Qilti teractfvcRcodnTr_SetPrefc tt^nccs(my Re nderer, kO AVendor Apple, 
kQA£ogirK_AppkS\V), 
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Q30bjact.Dispose(rayRenderer): 

// Create and set camera. 

myCamera w MyNevVtewPlannCamera(th^Window, cubeWidth); 

r for an orthographic camera, replace with: 

mvCamera - MvNewQrthographidJamcraf the Window. cubeWidth); 

7 

Q3View_Set Camera(myVlev. myCamera); 

Q30bject_Dispose(myCa[Bera) ; 

// Create and set lights. 

myLights = HyNewArabientQnlyLights(); 

f* for better looking lights, replace with: 
my Lights = MyNrwUghtsO; 

7 

Q3VievJ3etLightGrQup(][iyView, myLights]; 

Q30bj ect_Dispose (inyLi ghts): 

return myView; 


static Void RravGubcO 

{ 

TQ3ViewStaius myStatus; 

Q3VievJ>tar t He nd e rin g(gView); 
do 

( 

QBStyle.Submit(glnterpolation. gView); 

Q3StyIe Submit[gBackFacing* gView); 

CBStyle Submit: tgFi IlStyle* gView); 
i f (gTempCU beRm. a tion) 

Q3Tr at i s f o rm_Submil(gTempCubeRo talion. gVIev): 
Q'l Disp 1 ayG r ou p_£ubml t f gCubefiode 1 , gVlew) : 
royStatue - Q3ViewJ:ndRendering(gVlew): 

I while (myStatus ■“ kQSViewStatusRetraverse): 


static void AddCubic (TQiGroupObject tbeGroup, long rheX* long 
theY, long thf?2. 

TOSColorRGB 'theLeftCalor, TQ3ColorRGB 
*theRigbtCoIor. TOJColorRCB * iheFrontColor. 

TQSColorRGB "tbeBaekColar* TQ3ColorRGB 
•theTopColor. TQlCclorRGB *theButtomColor) 

I 

TQ3Geometry0bject myBox; 

TQIBoxData rayBoxDa1a; 

TQ3$t*l0bjeit faces [6]; 

TQ3Group0bjeci uCubie: 

TQ3 Tr a n s t o rmOb j ec t aT rang forma t ion; 

TG3Matrix4x4 aMatrix: 
short face; 

// create a rotation object, it doesn't rotate yet 
// but it will be adjusted after rotating the fat e 

aCubie " Q31iisplayGroup_NevO : 

Q3Mnlrix4x4_SetIdentity(feaHairix): 
aTrans format ion = Q'JBatrixTransfortOlewiAaMatrix); 
Q3Croup_Add0bjen. (aCiibie. aTr arts format ion) ; 
QlObjectJHsposeCaTransforraation]: 

// create the box itself 

myBoxData,faceAttrihuteSet - faces: 
myBoxData.bnxAttrlbuteSet = nil; 

my BoxtJa La. faceA11 rihttteSet[0] = Q3At tribut eSet_Wew{}: 

03 Attri.buteSet_Add (myBoxDaLa ♦ faceAitributeSet [0], 
kQ3A 1 1ribnteTyp«DiffuseColor, iheLeftColor); 
myBoxData* faceAttributeSet 111 = Q3AttributeSet _NevU ; 
Q3AttributeSet_Add (myBoxData.faceAttributeSet tl]. 

kQ3AttributeTypeBiffuseColor, theRightColor); 
myBoxData.faceAttributeSet[2] = QEAttributeSet New{); 
Q3AtTributeSet Add (tny Box Data. faceAttributeSet [2] , 
kQlAttributeTypMHffuseColor* theFrontColor); 
myBaxData.faeoAttributeSei13] = QlAttributeSet_ttew(); 

Q3AtiribuloSel_Add (tnyBoxData . faceAttributeSet [3] t 
kQ3AttributeTypel)iffuseColor, thellackColor) : 
myBoxData.faceAttributeSet i4j - Q3AtTribureSet_New(); 
Q3Attri&uteSet_Add(KLyBoxBata.faceAttributeSet l4j» 
kQ3At t ributeTy peDiff useColor, theTopColor ); 
myBoxData.faceAttributeSetf5l = Q3AttributeSet New(): 
QSAtrributaSet Add (my BoxData.faceAttributeSet. 

kQ3AttrIbuteTypeDiffuseColor. theBoitomColor): 
QBFointlU^Setf&myBuxLlata.origin, -l.S + theX, 0.5 ibeY, 
0.5 - theZ); 


Q3Vector3D_Set (kmyBoxData. orientation, 0 h 1, (3); 
Q3Vector3D_Set {ferny BoxData. major Axis. tl. 0, 1): 
Q3Vector3D_5et(femyBoxData.minorAxis, 1, 0* 01: 
my Box = Q3Box_Kew{ ferny BoxData): 
for (face =0: face < 6; facef+) 

If (myBoxData.faceAttributeSet[face1 I— 0) 

Q30bjcct_Dlspose {myBoxData. faceAttributeSet |fac.e]); 
GlGtottp^AddObjec t (aCubio. JnyBox): 

Q3 Ob j ec t_D is pose (my Bo x); 

G3Group_AddGbject(theGroup. aCubie): 
gCubiesltheXj [theYj[theZj - aCubie; 


static TQ3Group0bject MyNewHodel(const RGBColor cubeColors[6], 
const short cubleCalors[6][3](3]) 

I 

TQBGroupObject myGroup 0: 

TQ3ShaderObject myllluminaLionSbader ; 

TQ 3 Hat rix 4x4 aMat rix: 

TQSColorRGB Q3CubeColors [bj ; 

TQ3ColorRGB aGray - (0.25, 0.25, 0.251: 
long face: 

// convert RGBColor tuTQjOilmtGR 

for {face = 0: face < 6; faee++) 

l 

Q3CubeColocs(face], r “ (float)cubeColors[face].red f Dxffff: 
QJCubeColots[facej.g “ (float)cubeColors[tacaj.green / Gxffff: 
Q3CubeColors[face] lb - (float)cubeColorsI face].blue / Gxffff; 

I 

//Create a group lor the complete nuxle!. 

i f ((myGroup = QIDinplayGrmip NewQ) 1“ 0) 

l 

// Define n shading type for The gnmp 
// and add the >hader to the group 

my 111 tuni ng t ionShade r - Q3NUL1.11 lumination_Nev£): 

r for a better I<Hiking cuIk, replace with 
mylihimmaiionSbader - Q3lanibatllltimination New(); 
or 

mvl llu m iriLU ion Shader = Q3Rhi>ngTlluminatlon_New(); 

7 

Q3Croup_AddUbject(myCroup, myIlluminationShader); 

Q30bject_Dlspose(myIlluminationShade r): 

// create a rotation object, it doesn't route yet 
// but it will be adjusted after routing the tube 

Q3Hatrix4x4_SertTdentity{feaMar.rixS; 

gCubeRolat Ion w Q3Hatr i xTraiiafornJ4ew(AaKaT rl x}; 

Q3Group_AddGbj ect(rayGtoup. gCubeHot aU on); 

// add boxes for the cubics 
// left top front 

AddCubiefmyGroup. 0. 0. 0. 

&Q3CubeColors[cubieColors fkLef11[2][Oil. fea&ray. 
iQ3GubeColors[cubieColorpfkfrontl[0][Ol I, 
feaGray. feQ3CubnColt>rsleubleColor#;[kt!pl [0][2]] . feaGray): 
// middle top from 
AddCubie{myGroup, 1, 0* 0, 

kaCray, feaGray, feQ3CubeGdlors(<;ubie€olors[kFront] f 1] [0] ] h 
feaGray. feQ3CubeColors(cubleGolors |k(Jpj [Ij [2]], feaGray); 
// right top front 

AddCubie(myGroup. 2, 0. 0* 

feaGray. feQ3CubeColot:s IcubifiColors fkRight] |0] [0] ] . 
feQlCubfcCfilorsfcubleGolorsfkFrontl [J.JtOJl. 
feeGray. feQ3CubeColors [rub i pGo! ore (klip) (2] [2] ]. feaGray): 

// left top middle 

AddCubistmyGroup. (3, 0. 1. 

feQ3CubeColorsLcubieColors[kLeft][1J [0]J * feaGray, feaGray, 
feaGray. feQ3CubaColors[cubieColors[kUpl[0]11]J. feaGray): 
// middlf tttp middle 
AddGubie(nryGrQtjp ( l, 0 t 1 ( 

feaGray. feaGray. feaGray, 

feaGray, feQ3CubcColors{cubieColors[kUpltl]tl]), feaGray): 
// right top middle 
AddCubielmyGroup, 2, 0, 1, 

feaGray, feQlCubeCoiors[cubieColorsIkRightJ[1j[0]j. feaGray. 
feaGray. feQ3CubeColors[cubieColors[kUpl[2]]1]J 4 feaGray): 
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Searchable Databases 
Online Stores 
Info Baskets 
Guestbooks 


Conditionals 


File Writes 


Discussion Groups 


It's time for you to take a look at MGI 

MGI, a plug-in to 4D's award-winning server, WebSTAR, is 
designed to provide functionality to otherwise static web sites, 
whether for a private intranet or enterprise - class IS P/AS P. 
MGI was specifically developed to be used by web graphic 
designers with no scripting or programming experience. If 
you know HTML, you know MGI. And if you are a 
programmer, you can learn MGI by the time your pizza is 
delivered. You can try out MGI for free - right now - without 
obligation by downloading a fully - functioning demo at: 


iimcite iracKinc 
I/O Transactions 
A Time Calculations 
PGP Encryption! 
Token Tracking! 
Calendars 
Random Rotation 


http://www.pageplanetsoftware.com 


E - Cards 
Credit Bank 


SOFTWARE BUILT WITH YOU IN MIND 


PagePlanet Software Inc., 3252 Octavia Stn 


>t, Rafeigh, IMC 27606 


91 9,233,1 7^0 







The products you need, with the prices 
and service you deserve... guaranteed. 

Power Tools for Programmers! 





CodeWarrior Pro 5 


CodeWarrior Professional $ put everything you need for 
software development at your Fingertips: project management 
tools, text and resource editors, source and class browsers, 
compilers, linkers, assemblers, and debugger,Release b offers 
such features as RAD for Java, faster compile times, local and 
remote application debugging, IDE extensibility options and 
even tighter C/C + + compliance. Additionally, you can create 
applications for Windows 95/9&NT and Mat OS 8,x and Mac 
OS X From either host pfatform. [available in versions hosted on 
Mac or Windows] 


Spotlight is lire lirst Macintosh H Automatic Debugger" H can 
automatically locate run time errors in your code and display 
the offending source code line Unlike similar tools on other 
platforms Spotlight is easy to use No source code changes 
are necessary for application debugging. Spotlight can 
automatically check Tor wild pointers, memory leaks, 
overwrites, underwrites, invalid dereferencing of handles, and 
even louiixj* p.n .imoter validity checking spotffghl Knows 
Macintosh verifying parameters to over 400 toolbox caiis 


$189 


Installer Maker 6.5 I OK 


Whether you're a developer of high-end, complex applications, 
simpler utilities. sFiareware/freeware, an IS manager or an ISP 
who needs to distribute files quickly and easily, the new 
InstallerMaker is the complete installation solution for you 
Utilizing the power of the new Stufflt Engine, InstallerMaker 
creates installers faster and smaller than ever, decreasing 
download time off servers and reducing the number of disks 
needed to distribute installers. These Lime and cost savings go 
straight to your bottom line! 


$219 


VOODOO Server 


VOODOO Server is a version control system for software 
developers using Meirowerks CodeWarrior under Mac OS. 
VOODOO Server and the corresponding VOODOO clients (the 
included CodeWarrior VCS plug-in and the VOODOO Admin 
application] are designed to offer reliable and robust version 
control features while minimizing the administrative overhead 
that usually accompanies version control. If you're a single 
programmer or managing a team of developers, version control 
can make or break your project. Do it right, with VOODOO 


Resorcerer 2.2 


Future BASIC 3 


Resorcerer is the only supported general purpose resource editor 
lor Macintosh Relied upon by thousands of Mac developers, 
Resorcener features a wealth of powerful yet easy-to-use tools for 
easier, faster, and safer editing of Macintosh data files and 
resources. Whether you have to parse a picture, debug a data fork, 
design and try out Balloon Help, create a scripting dictionary, create 
anti uiiused icons, design and edit a custom resource with 40,000 
fields in it, create C source code to run a dialog, or any of hundreds 
of other resource-related tasks. Resorcerer's magic will quickly save 
you time and money. 


i'll ! 


$256 


One of the most flexible and powerful development 
environments on the Macintosh today 1 Easily create programs 
with the visual program editor, drop into the BASIC editor to 
define powerful logic with the worlds easiest programming 
language, or work directly with the Macintosh toolbox. The 
only BASIC compiler on the market that gives you 100% access 
to all of the power of the Macintosh toolbox! 


and hundreds moret 





Page Charmer 2.0 

SI 39 


WebTen 

$349 


Faces pan 3.0 WebSpice Animations Power Key 

TootsPlus Lite $179 WebSpice 1,000,000 S89 MkLinux Rebound 


■fia? - 

ZSP 
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PO Box 5200 ■ Westlake Village, CA • 91359-5200 * Voice: 800/MACDEV-1 (800/622-3381) 
Outside US/Canada: 805/494-9797 * Fax: 805/494-9798 * E-mail: orders@devdepot.com 

www.devdepot.com 

Master the Web! 


Monitor the bandwidth usage of up to five different machines on your 
network! Do you need to upgrade your Webserver? How turd is youi 
eMail server working? Are you getting all the bandwidth you're 
paying for? Mot only can CyberGauee answer all these Questions, 
new features allow CyberGauge to eMail or page your network 
device becomes unresponsive r passes a threshold of usage you 
define - an essential first line of defense for early detection of dental 
of service attacks and necessity for warning you and tracking quality 
of ISPs that may have brown outs and shutdowns. 


WebSTAR Server Suite is a complete set of powerful and easy- 
to use internet servers for the Mat OS. Effortlessly serve web 
pages, host email accounts, publish databases, and share files 
all with a single application on one Mac! WebSTAR Server Suite 
ts perfect for Internet or Intranet serving, single or multiple 
sites, smalll and large businesses it's power and easc-of-use 
saves any organization time and money, 


NEW! 


: unnef Web Is the ultimate web analysis solution for 
yrofessionata Specifically designed for profiling web site usage 
ind monitoring customer usage patterns, Funnel Web is ideal for 
Examining set vet performance and online effectiveness Funnel 
’Veil can analyze log fife formats from any server, WebSTAR, 
MebTen. even Unix or NT hosted errors Discover the most 
>opular pages on your site, track server loads & optimize server 
)erformance, profile visitors based on organization, domain 
tame. country, browser, etc Funnel Web does it afl! 


NetBarner offers a Personal Firewall. Antivandal protection, and 
Internet Filtering. Protect your machine from intrusions by internet 
or AppleTalk. Incorrect passwords and Individual actions are 
logged, you are alerted to hostile actions, and intruders are easily 
isolated, internet f iltering allows you to be sure that passwords, 
credit card numbers, and other sensitive information can never be 
exported from your computer the content itself is filtered before 
any transfer! (Rated 4 mice by Macworld Magazine] | 


and great hardware solutions! 


Do you need 4 monitors and 4 keyboards for your 4 servers? 
With Dr Boll MonFSwitch you can connect a single keyboard 
and monitor to up to 4 machines at once! A simple Rick of a 
switch directs the video input and keyboard commands to the 
appropriate CPU! Available in USB and ADB models, with 2 
or 4 machine support, and bundles with USB PCI cards so 
you can mix and match USB and ADB machines with the 
same Monl-Switch! GraaL lor programmers to do back 
ground compiles, ideal for server rooms overcrowded with 


lAdd two USB ports to your older Macintosh. Connect up to 
’i 27 devices to the Universal Serial Bus (USBJ that is 
Apple's new standard for desktop connectivity. USB mouse 
devices, keyboards, joysticks, game controllers, printers, 
scanners — connect them all to your current computer. 


As tow as 


monitors and keyboards! 


WebSTAR Server Suite 4.2 


NetBarrier 


Funnel Web Pro 


Dr. Bott Moni Switch adb or usb 


Macsense USB Full Size Keyboard 

Macsense Internet Sharing Router 

Just plug this keyboard into your Mac and start typing! The 

UKB-600 keyboard from Macsense is designed to get you 

worries It features two tone bansJucefit design, colored to 

match your favorite flavor of Macintosh. It offers soft touch . 

with positive tactile feedback aixl build built in USB port on 95 

either side of the keyboard. Includes a b' USB cable and is ■ 

100% Macintosh compatible, simply plug and play, as easy ” 

as Macintosh! 

Looking to get your whole office online without shelling out f i^TII 

^ thousands of dollars? If so. the XRouter internet Sharing 

Hub offers the perfect solution. This amazing Ethernet*^ 

Ethernet hub connects an entire network of up to 2S2 users 
to the Internet using only one ISP account and one Cable or 

DSL modem! * 

$199 






























// left top back 

AddCubie(myGroup, 0. 0. 2. 

&Q3CubeColorsfcubieColors[kLeft3 [0][0]J * &aGray ( baCray, 
&Q3CubeCoIors[eubieColors[kBackj[2][0]]■ 
&Q3CuheCo1ors[eubieColors[kUp][Q][0JJ. fcaEray): 

// middle top back 
AddCubie(myGroup, 1, 0, 2* 

&aG ray. &aGr ay, &aG ray t 

&Q3CubeColorsleubieColors[kBack] fl][0]] T 

&Q3CubeColors[eubieColors [klip] [11 fOl)* fcaGray); 

// right lop hack 

AddCubic(myGroup, 2, 0, 2, 

kaGray, SiQ3CubeColorfr [eubieColors[kRight] [2] L0j j, &aGray* 
&Q3CubeColors[eubieColors[kBack| [0j tOj J . 

AQSCLibeCgl ors [eubieColors [kCpj [2] [Q] ], &aGray): 

// left middle front 

AddCubie(rayCroup, 0, 1, 0* 

&Q3CubeColoEslcubieColorsfkleft][2][1] 1 , fcaGray, 
&Q3CubeColors[eubieColors[kFront] [01 [lj] * 

4aGray, kaGray, &«Gray): 

// middle middle front 
AddCubie(myGroup. L 1* 0* 

&aGray, kaGray* &G3CubeGoIors[eubieColors[kFront][1|[I] 1 , 
b aGray, fcaGray, &aGray); 

// right middle from 
AddCubie(myGroup. 2, 1, 0, 

fcaGray, &Q3CubeColorsfeubieGalors[kRighl] [D] [1]], 
&Q3CubeColors [eubieColors[kFrontI[2][lj]. 
fcaGray* AaGray. feaGray]: 

// left middle middle 

AddCub ie {toyGroup. 0, 1. 1. 

&Q3CubeCole>rs[eubieColors[kLeft] [1] [111. taGray, kaGray, 
baGray, taGray, & aG ra y): 
ft middle middle middle 
r invisible 

AddCubicCmyCiroup, i t J, I, 

&a(!ray* &uflny, Mi ray, 

&aGray ftflClff, &nGray); 

7 

ft right middle middle 

AddCubie(myGroup, 2. 1, 1. 

fcaCray, &Q3CubeColors[eubieColors[kRight] [i] [l]j, ktGtay, 
ft&Gray, AaGray, AaGroy); 

ft left middle back 

AddCubie(myGroup, 0, 1, 2, 

iQlCubeColors[eubieColors [kbeftj [01 U] ], AaGray. £aGray, 
&Q3CubeColors[eubieColors[kBack][21 till * AaGray. fraGray)* 
// middle middle back 
AddCubie{myGroup. 1. 1, 2, 

fcaGray, fcaGray, AaGray, 

&Q3CubeColors TcubieColorn[kBack][1 ][ 1]], feaGray , fcaGray j; 

// right middle back 
AddCubie(myGroup. 2* 1, 2 T 

fcaGray, 6Q3CubeColors [eubieColors [kRight] [2] f 1] ], AaGray, 
&Q3CubeGolors[eubieColors[kfiackj [0][1]]. kaGray, taGray): 

// left bottom from 
AddCubie(myGroup. 0* 2. fl* 

6iQ3CubeColors[cubieColars[kLeft] [2] [2]]. AaGray, 
&Q3CubeCalarsUubl eColors[kFrontJ [0] [2 ]J * 

&aGray, kaGray. ftQ3GubeColors[eubieColors[kDownJ[0J[0]]); 

// middle bottom front 
AddCub1e(myGroup * 1, 2, 0, 

kiGray. fcaGray. &Q3CubeCoIors[eubieColors[kFrontI[1][2)1, 
AaGray. &aCray, &Q3CubeColors[eubieColorsfkDown] jI][0]jj; 

// riglu bottom front 
AddCubie(myGroup. 2 , 2. 0, 

iaGray. 4Q3CubeCoUrs[eubieColors[kKightJ [0] [2]J . 
&Q3CubeColoro[rubfeColors[kFront] [2] [2] j* 

GaGray, iaGray* &Q1CubeColors[eubieColors[kDownJ[2j[0]j); 

ft left bottom middle 

AddCubie(myGroup. Q t 2. 1, 

&Q3CubeCoiors[eubieColors[kLeft][1][2]] t kaGray. AaGray, 
&aGray t &aGray, 4Q3CubeColors[eubieColorstkDowu][0][l]J): 

ft middle boLlom middle 
AddCubie(tayGroup, 1. 2, 1, 

fcaGray, AaGray. ^aGray^ 

taGray, iaGray, WCubeColors [eubieColors [kDown] [1] [1] ]); 


if riglu boitott) middle 
AddCubie(myGroup. 2, 2. 1. 

&aGray, &Q3CubeColorsfeubieColors[kRigfil] [I] [2j ] , kiGray, 
SaGray, AaGray, fcQ3CuheColors[eubieColors[kliown][2j[ij I); 

U left bottom back 
AddCubie(myGroup, 0 t 2, 2, 

&Q3CubeCoiars[eubieColorsIkleftI[0](211. &aGray. kaGray, 
&Q3CubeColors[eubieColors[kBack1[2][2]1, &aGray, 
fiiQlCubeColorsieubieColorsfkBoviij [0] [2]]); 

// middle bottom Ixtck 
AddCubie(myGroup. 1* 2, 2. 

&aGray, &aGray, &aGray, 

AQ3CubeColprs[eubieCoXurs[kBackJ LI][2jJ . iaGray, 
&Q3CuboColors[eubieColorsjkDownJ [I][2]]): 
ft right lx)ttt>m hack 
AddCubie(myGroup. 2, 2. 2 t 

firaGruy. 4<Q3CubeColor£ [eubieColors [kRightl [2][2] ]. fcaGray, 
&Q3CubeColore[eubieColors[kBack][0][2]]. &aGray, 
&Q3CubaColorajeubieColors[known][2][2]]); 

) 

return myGroup; 

I 

void InitCube( 

CWindovPtr cubeWindov, 
const RGBColor cubeColors[6], 
const abort eubieColors[6][3] [3] . 
short cubeWidth, 
short stepSize 

) I 

1 ong x, y, z; 

for (x = 0; x < 3; x++) 
for (y * 0; y < 3; y++) 
for (z = 0: z < 3; z++) 
gCuhies [xj [y] fz| - 0; 

SetPort{(GrafFLt)eubeWlmluw); 

gStepSize = stepSize; 
gTempCubeRotation ® 0; 
gCubeRotation = 0: 

QllnitializeO: 

ff sets up the 3d il;im for the scene 
ft (irate view for QuickDraw 31) 

gView = HyNewView(cubeWindow t cubeHIdth); 

// the main display group; 

gCubaHodel = MyNewHodeKcubeColorn* eubieColors): 

ft the drawing styles; 

glnterpolation " 

Q31nlerpolmionStyls;„New(kQ31nterpolationStyleNone); 
kFacing ~ 13BarkfacingSty 1 e_New ( kQ3BacktacIngStyleReiaove): 
gFillStyle = G3FillEtyle_New(kQ3FillStyleFllied); 

DrawCubeO; 

1 

void QuarterTurn( 

CubeFsco face, 

TurnBireel ion direction 

3 t 

long ip x, y. z\ 

longaFirstX, aLastX, aFirstY, aLastY* aFlrstZ, aLastZ; 
TQlMatrix4x4 aCubieHa t rix. uRorat IonKat rix; 

TQlRotuteAboutAxieTrannff>rmGata aRoLationdata; 
TQ3TrannformOhjert aFareRntatIon; 

TQ3GrnupPosltionaFos: 

TQ3Group0bject aCubie: 
long stepsToTurn; 

aFirstX = 0: 
aLastX - 3; 
aFirstY - 0; 
aLastY - 3; 
aFirstZ = 0; 
ahastZ = 3: 
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// creak a reunion abjcit 
switch(face) 

I 

case kFront: 
l 

If (direction = kCIockwifle) 

Q3V&ctor3()_Sci (SaMoiat landsts.orientation, Q.0, 0.0, 1.0) s 

else 

Q3Veetor3DLStt(fcaRotatiandata.orientation, 0.0, 0-0, 1.0); 
aLastZ = 1; 
break; 

I 

case kBack: 

I 

if (directinn = kClockwise) 

03Vet i or3D__Sn L (ka Ro La L toutfats - or [ ent at ton, 0.0, 0.0, 1.0); 
else 

Q3Vedtot30_Set(6aRutationduta.orientation, 0.0. U.0, 1 T 0); 

aFlrstX = 2: 
break; 

I 

case kLeft; 

I 

if (direction ” kClockwiee) 

ClSVoctor3DjSet(feaRotatiandalo.orientation, 1.0, 0.0, 0.0); 
else 

Q3Vectar3DJ>etUaRotationdata.orientation, -1.0. 0.0. 0.0): 
aLastX = 1: 
break: 

I 

case kRight: 

r 

If (direel ion — kClockwise) 

(J3Vector3tLSet(ftaKotstlcmdata.orientalion, -1,0. 0.0. 0,0); 
else 

Q3Vector3D_Set(fcaRotationdata.orientation. 1,0, 0.0. 0.0): 
aFlrstX - 2: 
break; 

1 

case ktlp: 

If £di ret'Lion “ kClodcwise) 

Q3Vector3D,,SetUaKotationdata.orientation. 0-0. -1.0. 0.0): 
else 

Q3Vector3D_Eet(iaRotationdata.orientation. 0,0, 1.0, 0.0): 
aUstY * i: 
break: 
i 

case kOown: 

f 

if (direction = kClockwise) 

03Vector3D„Set(traKotationdata,orientation, 0,0, 1.0. 0.0); 
else 

03Vector3D_Set(fiaRotstiondata.orientation, 0.0. 1,0, 0,0): 

aFirstY = 2; 
break: 


Q3PoEnt3TLSct (StaRoiatlumhlLa,origin, 0,0. 0,0, 0,0); 
aRatallondaLa.radians ~ 0.0; 

aFaceRotation - Q3RotateAboutAxisTransform_Wew(&aRotaiiondata); 
// add ilic rotation object lo c;idi cubic in die face 
for (x « aFirstX: x < aLastX: x+f) 
for £y = aFltstY; y < aLastY: y++) 
for (z * aFlrstZ: z < aLastZ: zlt) 

1 

QlGroupJkft First Posititm(gCubIes[x3 [y] [z], &«iPos); 
Q3Grotip_AddObjectBefore (gCubies [x] [yj [zj, aPos, 
aFaceRotation); 

I 

// draw and adjust die angle 

stepsToTum * gStepSize / hi 

for (i = I; 1 < stepsToTurn: i+l) 

t 

03 RoiaicAboulAxisT ran s form_SoL Angle(aFa e eRo t a tinn, 

(2.0 1 KQ3Pi * i / gStupSize)); 

DrawCubeO; 

[ 


// set the angle to 90° and adjust the rotation of each cubic 
Q3Rot a t eAb out Axisir an s f ora_Se t Ang Ie(a Fa c e Rotation, 

(kQ3Pi / 2.0)); 

Q3Transfonn_&etHatrix (aFaceRotat ion, kaRotatianMatrix): 
if UFaceRotaticm) 

Q30b j ect_DisposefaFace Rot a 11on); 
for (x - aFlrstX: x < aLaslX: x++) 
for (y “ aFirstY; y < aLastY; y++) 
for (z “ aFirstZ; z < aLastZ; z++) 

l 

Q3Group_GetFirstPosition(gCubies[xj [y][z] , fraFos): 
aFaceRotation “ Q3Group_RemovePosition(gCubies[x][yjUJ. 
aPos); 

if (aFaceRotation) 

Q30bject_Dispose(aFaceRotation); 
Q3Group_GelFlrstPositionOfType(gCubiesfx][y] [z] . 

kQ3TransforufTypeMatrix, &aPos); 
Q3Group_GetPosition0bject(gCubiesU] (y) [zj , aPos, 
^aFaceRotation); 
if (aFaceRotation) 

I 

QBKatrixTransform Get(aFaceRotation, iaCubieMatrix): 
Q3Matrlx4x4_Multiply(kaCubieHatrix, fiaRotatianWatrix, 
SaCubleKatrix); 

G3MatrixTransfurm_5et(aFaceRotation, kiCubieMatrlx); 
Q30bject_Dispose(aFaceRotation); 

) 

) 

DrawCubeC); 


// mute rubies in gCubio 

switch(face) 

I 


case kFront: 
f 

if (direction =■ kClockwise) 
( 


aCubie 

gCubies[ 0 ]| 0 ]( 0 ] 
gCubies [ 0 ] jzj [ 0 ] 
gCubies[ 2 ] [ 2 ] [ 0 ] 

gCubies{ 2 ] joj [ 0 ] 

aCubie 

gCubies Li J L 0 J lOj 
gCubies[0J [1][0J 
gCubies11]12][0j 
gCubies[2] fl] fOl 

) 

else 


gCubiesIO][01[Dj : 
gCubies[0][2](0) ; 
gCubies[2][2] [0] ; 
gCubics[2](Oj [0]: 
aCubie; 

gCubieellj [0]lOj ; 
gCubies[0](1j [0]: 
gCubies[1]12j [01; 
gCubies \ 2 } (11[0); 
aCtibie; 


t 


aCtibie 

gCubieslOj 12J [Oj 
gCubies[0]101[0l 
gCubies[21[01 [01 
gCubiesf21f2][0J 
aCuhie 

gCubies[f]£2)[0] 
gCubies[0] [l ] [0] 
gCubies[1]fo][0] 
gCubies[2][lj [0] 


gCubies[0J (2j [0] 
gCubies [Cl [OHO] 
gCubies(21[0][0] 
gCubies[21[2][01 
aCubic; 

gCubies[i][2][0] 
gCubies [0] IU [0) 
gCubies[1](03 [0] 
gCubies[2)[13 [01 
aCvibie: 


break; 


case kBack: 

( 

if (direction ” kClockwise) 

I 

aCubie * gCubies[0][2]£2]; 

gCubies[0] [2] [2] = gCubies(0)[Oj [Zj; 
gCubies[OJ [0][2] * gCubies[2j l0||2j; 
gCubies[21[0] [2] - gCubies[2][2][2]; 
gCubies[2][21[21 - aCubie: 


aCubie 

gCubies f1][21 [21 
gCubies[0] [1] [ZJ 
gCubies[l] [0j [2] 
gCubies[2l[lj [2] 


gCubies [11 [2] [2h 
gCubies[0l [1] [2]: 
gCubies[11[□! [2]; 
gCubies[21[lj[2] ; 
aCubie; 


\ 
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else 

1 


aCubie 



- 

gCubies[0] 

[01 

[21 

gCubies[0] 

EO] 

[2] 

“ 

gCubiesf0] 

[2] 

[2] 

gCubies EG) 

t2] 

[2] 

* 

gCubies[2] 

[23 

[2] 

gCubies [2] 

[21 

E2] 

- 

gCubies [2] 

[0] 

[2] 

gCubies[2] 

to] 

E2] 


aCubie; 



aCubie 


[2] 

m 

gCubies[lj 

[OJ 

[2| 

gCubies E11 

[0] 

= 

gCubiestO] 

[11 

[2] 

gCubies[0] 

[1] 

[2] 

* 

gCubies[1] 

[21 

[2] 

gCubies[1} 

[2] 

[2] 

** 

gCubies[2] 

[11 

[21 

gCubiesUl 

1 

ED 

[21 

* 

aCubie; 



1 

break; 







i 

case kLeft: 

i 







i 

if (direction - 

= kCiockwise) 



i 

aCubie 




gCubies[0l 

[0] 

[21 

gCubies[0] 

to] 

[2] 

* 

gCubies[oj 

'll 

m 

gCubies[0] 

121 

[2] 

“ 

gCublesfO] 

[2] 

[0] 

gCubies[01 

[2] 

to] 


gCublesjo) 

[0) 

[0] 

gCubies [0j 

[01 

|0J 

■ 

aCubie; 



aCubie 




gCubies[0j 

[OJ 

[I] 

gCubies[0] 

to] 

fl] 


gCubies[0] 

[1] 

[2] 

gCubies[0] 

[1] 

[2] 


gCubies[Ol 

[21 

11] 

gCubies[0] 

[2] 

[1] 

** 

gCubies[0I 

[1] 

[0] 

gCubies(OJ 

UJ 

EO) 


aCubie: 



i 

else 







( 

aCubie 

[2] 

[2] 

» 

gCubies [Oj 

[2] 

(2) 

gCubiesfO] 

= 

gCubies(0] 

[0] 

[2] 

gCubies[0] 

[0) 

[2] 


gCubies[OJ 

10] 

[01 

gCubies[0] 

[0J 

[0J 


gCubies tOj 

[2] 

[01 

gCubies[0] 

UJ 

to) 

= 

aCubie: 



aCubie 




gCubies[0] 

[2] 

[1] 

gCubies[0 J 

[21 

[11 

“ 

gCubies[0] 

U1 

[2] 

gCubies[0] 

[1] 

[2] 


gCubies [o] 

[0] 

[I] 

gCubies[0] 

[0] 

[1] 

* 

gCubies[0] 

[11 

[0] 

gCubies[0] 

[I] 

to] 

* 

aCubie; 



r 

break; 

i 







1 

case kKight; 

i 







if (direction = 

= kClnckvise) 



i 

aCubie 



- 

gCubies[2] 

[2] 

[2] 

gCubies[2] 

[2] 

[21 

- 

gCubies[2] 

[0] 

UJ 

gCubies [ 3 ] 

to] 

[21 

=■ 

gCubies[2j 

[0] 

[0] 

gCubies[2] 

[0] 

[01 

= 

gCubies[2J 

[2] 

[0] 

gCubies[2] 

[2] 

[01 

* 

aCubie ; 



aCubie 



• 

gCubies[2] 

[21 

EH 

gCubies[2] 

[2] 

[ll 

- 

gCubiesf2] 

HI 

[2] 

gCubiesi2] 

[11 

[2! 

— 

gCubies[2] 

[0] 

[1] 

gCubies[2] 

[0] 

m 

= 

gCubies[2] 

[1] 

[0] 

gCubies[2] 

| 

Ill 

[0] 

* 

aCubie; 



1 

else 

t 







l 

aCubie 



- 

gCubies [21 

[0] 

!2) 

gCubies[2j 

[01 

[2] 

« 

gCubies [21 

[2] 

[21 

gCubies[2] 

[2] 

[21 

- 

gCubies [2] 

[2] 

[0] 

gCubies[2 j 

E21 

[01 

*= 

gCubies [2] 

to) 

Eo] 

gCubies[2l 

[0] 

[0] 

= 

aCubie; 



aCubie 



- 

gCubies[2j 

[0] 

HI 

gCubies|2 ] 

to] 

[1] 

s 

gCubies [2] 

[1] 

[21 

gCubies[2] 

til 

[2] 

= 

gCubies[2] 

[2] 

[11 

gCubies[2] 

[2] 

[1] 

= 

gCubies[2] 

U1 

[01 

gCubies | 2] 

1 

UJ 

[0] 

* 

aCubie; 



i 

break: 

1 







i 

case kUp: 








t 

if (direction *” kClockvise) 
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» 


aCubie 

gCubies[Ql TO]f2] - 
gCubieajoj [0j[01 = 
gCubies[2l[0][0] - 
gCubies[2] [0][2J * 
aCubie = 

gCubiesllJ loj12 = 
gCubies[Qj [Oj [I - 
gCubies[lj [0j[0j - 
gcubi^ranonn - 


gCubies[OJLOJ [21 
gCubies[oj[0][0J 
gCubies[21[0][01 
gCubies[2][oj [2] 
aCubie; 

gCubies D][0] [2\ 
gCubies[0][0][1] 
gCubies[13[0]lOj 

gCubies[2][O][I] 
aCubie; 


else 


aCubie 

gCubies[2][0] [2] 
gCubies [2] [Q] [0] 
gCubies[0j jo][l)j 
gCubies f0][0](2) 
aCubie 

gCublesDHO] [21 
gCubies[2][0]f3] 
gCubies[J] [0] [0] 
gCubies£0] [0j [lj 


gCubies[2j[0] [2] 
gCubies [2][0][Q] 
gCubies [0] [0] [OJ 
gCubies[0j(oj [2] 
aCubie; 

gCubies[i][OJ L2J 
gCubies[2][0]|ij 
gCubies[it [G] [0] 
gCubies[Oj [0] [lj 
aCubie; 


break; 

J 

case kDown: 

l 

if (direct ton ■* kClockvise) 

i 

aCubie = gCubie$[2][2][2] 

gCubiesi2][2][2] - gCubies[2][2][0] 

gCubies[2J [2j lOj * gCubies[0][2][Q) 

gCubies[Oj [2][01 “ gCubiesjo][2j[2] 

gCubies[01 [21 [2[ - aCubie; 

aCubie - gCubies[lj[2] [2] 

gCubie0[ll [2H2l = gCubies[2] [2] [ 1 i 

gCubies[2][2J[1] - gCubies[1J [2][01 

gCubies [l)[2j[0] “ gCubieatOlUHU 

gCubies[oj [2] [1] - aCubie; 

» 


else 

I 

aCubie - gCubies[0] [2 j [2] 

gCubies[0] [2] [2] - gCubies[01[2][0] 

gCubies[0][2][0] - gCubies[2J [2l[01 

gCubies[2][2][0l = gCubies[21 [2][2] 

gCubies[2] [2 J [l] = aCubie; 

aCubie ** gCubies[1][2] [2] 

gCubies[lj [2J[2] = gCubies[0][2][lj 

gCubies[oj [2][lj - gCubies[lj[ 2 ) [oj 

gCubies!ll[2]lOl - gCubies[2j [2\ [i] 

gCubies[21 [21 [11 « aCubie; 

! 

break; 


void RotateCube( 

CuheAxis axis, 

TutbOireetiou direction, 
short stepsToTurn 
) [ 

TQMotateAboulAx I sTransformData aRntationdata; 
TQ3Hatrix4x4 aGubekolatiunMaLrix* aTcmpMatrix; 
long i; 


// create a iutatkm object 

switch (axis) 

t 

case kFrontBack: 

[ 

if {direction kClockwise) 

Q3Vector3D_SetUaRotationdata.orientation, 0.0. 0.0, -1.0}; 
else 

Q3Vectar3D3et (kaRotationdata,orientation, 0.0. 0.0, 1,0); 
break: 

J 


case kLeftRight; 

\ 

if (direction ““ kClockvise) 

Q3VecLor3D_Set(feaRotationdata.orientation, 1.0, 0.0, 0.0); 
else 

Q'3Vector3D_5et(fcaRoiatlondata.orientation, -1*0, 0.0. 0.0); 
break; 

I 

case kUpDown: 

I 

if (direction “ kClockvise) 

(J3Vector3D_Set(&aRotationdata.orientation, 0.0, -1.0, 0.0): 
else 

Q3Vector3D_Sct(&aRotatii>ndata + orientation, 0.0* 1,0. 0.0); 
break; 

I 

] 

Q3Point3D_Set{&aRotationdata.origin, 0.0, 0.0, 0,0): 
aRotationdata.radians - 0.0; 

// the cube has been rotated, rotate Uit orientation of the rotation 

Q3MatrI xTrsnsfom.Get(gCubeRotation, fcaCubeRotationMatrix}; 
Q3Vectar 3D_Trannfr>rm(ftaRota 13ondata .o rientation. 

baCubeRotationMatrix, kaRotationdata,orientation); 
gTerapCubeKotation = 

Q3Rotat eAb outAxisT rans f orutile v( La Rot a tiond a t a); 

// draw and adjust the angle 

for (i = ]; i < stepsToTurn; i++) 

l 

Q3Rot a teAboutAxisTransform SetAngle{gTempCubeRotation. 

(2,0 * kQ3Pi ‘ i / gStepSize)); 

OrawCubeO : 

I 

// set the angle to 90* ami adjust the rotation object of the cube 

Q3Ro t a te Abou tAxisT rans £ orm_5e tAn gle(gTe m pCub eRo L a tion, 

(2.0 * kQ3Pi * atepsToTurn / gStepSize}); 
R3Transform _GetHatrix(gTempCubeKotation, ^aTeropHatrix); 
Q3MatrixTransfom Get (gCubeRotation, SiaCubeRotationHatrix); 
Q3Mai r ix4x4_Mul r. 1 ply (&aCubeRotationMatrix. ^alempMatrix, 
^aCubeRoiatlonMartix); 

Q3MatrixTransform_Sol(gCubeRotatlnn t iaGubeRotationMatrix}; 
// don't need gJentpCul>eRoTatiofi anymore t dispose it 
if (gTempCubeRotation) 

Q30bject Dispose(gTempCubeRotation); 
gTemp CubeRota tion - 0: 

OrawCubeO ; 


v oid Te rmCube(void) ( 
longx, y. z: 

Q30bject_Dispose(gView); 

Q30b jeer Dispose(gCubeModel): // <#xt m the scene bring modelled 
Q3Qbjeet Dispose(gCubeRotation); 
for (x = 0; x < 3; xit) 

I©e (y “ 0; y £ 3; y++) 
for (z = 0; r. < 3; z++) 
t 

if (gCubies[xj [yj [xj) 

Q3Object_0ispose(gCubiesjx] fy][xj): 

// object in the scene being modelled 

I. 

Q30bject Dispose (ginterpolation); // liuopolatiofi styk used wIkh tendering 
Q30b j ec t_Dispos^(gBackFacing): 

// whether to draw shape# that lace away from the camera 
Q30bjeet_DispoKo(gFil1 Style}; 

U whether drawn as solid filled object or decomposed to components 
Q3Exit(); 0Q 
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QUICKDRAW 
3D TRICKS 


By Tom Djajadiningrat and Maarten Gribnau 


Cubby: Multiscreen Desktop VR Part I 


Multiple views and 
mirroring images in 
QuickDraw 3D 


Summary 

In a series of three articles we 
describe how to implement the 
visualization pari of a Cubby, a desktop 
virtual reality system which uses three 
orthogonally placed head-tracked 
screens. This series will give you an 
understanding of how this type of three 
dimensional display works and show 
you how easy it is to implement using 
off-the-shelf components. To facilitate 
implementation wc use Apple's 
QuickDraw^!) API. Even if you are not 
interested in virtual reality display 
technology, you may still be interested 
in the QuickDraw 3D techniques 
presented here. The most important 
ones are multiple views on a single 
model and the mirroring of images 
without [he use of offscreen GWorlds. 

Introduction 

Cubby is a desktop virtual reality 
system developed at Delft University of 
Technology (Djajadiningrat ct a), 1997; 
Djajadiningrat, 1998), Cubby uses three 


orthogonally placed head-tracked screens which form a cubic 
display space { Figure I), Through the coupling of the 
perspectives on the screens to the head-movements of the 
user in real-time, the illusion is created that a virtual scene 
stands inside the display space. Figure 2 shows a user in 
front of Cubby, Figure 3 shows a chair inside Cubby's 
display space from four perspectives as generated by four 
different head positions. Because of the way the screens are 
placed, Cubby allows the virtual scene to be viewed from a 
wide range of visual angles (.see movie ‘visualization.mov). 
And since the virtual scene appears in from of rather than 
behind the screens, the user can get at the objects in the 
virtual scene with an instrument without the screens forming 
an obstruction. This makes it possible to manipulate objects 
by means of an instrument at the place where they appear 
(see movie ‘manipuIation.fiiov’X The 3D impression that 
Cubby creates is based purely on head-tracking. It does nor 
use stereo though of course this could be added. 



Figure L The Cubby setup. 


Tom has calculated that if he could convince the current top contestants to refrain from taking part in the Programmer s 
Challenge and he were to submit a proposal for a Challenge every month, he could he leading the pack by as early as 
Christmas 2010, Just in case this clever ploy to achieve fame fails, he continues to hone his personal collection of 
irreconcilable skills, 

Maarten lives in a binary world His research is about two-handed interaction with 3D graphics. But recently, he realized 
that Ills bimanual interfaces fall short when his twins started to interact with his computer He is now thinking about 
rewriting Nanosaur and implement four-handed interaction. 
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Figure 2. A user in front of Cubby. 



Figure 3* Four persjKtcUves on a desk chair m generated 
hy different head positions. 


Technically, Cubby is similar to a CAVE (Cruz-Neira et 
aL t A CAVE is a virtual reality environment in which 

the walls anti Moor of a room form projection screens. A 
CAVE measures approximately 3x3x3 metres, while 
Cubby’s display space is only 0.2x0.2x0.2 metres. Thus 
from a technical point of view you can think of Cubby as 
a miniature CAVE. From an application point of view, 
however, Cubby and CAVE are quite different. With a 
CAVE, the user is inside the cubic space while with a 
Cubby the user is outside it. This gives each system its 
pros and eons. With a CAVE, the virtual scene is all around 
the user. It is therefore well-suited to panoramic viewing 
and walkthrough or rollercoaster types of simulation. 


Because of ius large size it is difficult to realize accurate 
head and hand tracking with the currently available 
tracking technology. With a Cubby the user looks upon the 
virtual scene as if it were an object. Cubby's workspace is 
much smaller than CAVE’s, but because of this, it is 
possible to realize accurate tracking of head-position and 
instruments. Cubby is therefore well-suited to precision 
tasks such as surgical simulation and computer aided 
design. Other advantages of Cubby are that it consumes 
little space, is relatively low-cost, and can be built using 
consumer grade off-the-shelf technology. 

This article describes how to implement the 
visualization part of a Cubby in QuickDraw 3D. It will 
give you a grasp of the technology behind multiple screen 
head-tracked displays such as Cubby and CAVE. Even if 
you are not interested in such technology, you may still 
be interested in the QuickDraw 3D techniques presented 
here. They are multiple views on a single model and die 
mirroring of images without the use of offscreen GWorlds. 
We also include a section troubleshooting, to help you get 
Cubby running, and a section Tidbits, with suggestions to 
further improve Cubby. 

Cobby on Power Macintosh 
W hat you should know' 

We assume that you ;ue familiar with the basics of 
QuickDraw 3D programming. If you have not dealt with 
QuickDraw 3D before w r e suggest that you have a look at 
the introduction to QuickDraw 3D in Develop 22 
(Thompson and Pernicola, 1995) or at chapter nine 
'QuickDraw 3D’ of Tricks of the Mac Game Programming 
Gurus’ (Greenstone, 1995). 

We also assume that you are familiar with Part I and 
IL of ‘Desktop VK using QuickDraw 31>\ two MacTech 
articles that appeared in July and August of 1998 
(Djajadmingrart and Gribnau, 1998; Gribnau and 
Djajadiningrat, 1998). 

Required hardware and software 

To try out the QuickDraw 3D techniques in this article 
you need a PowerMacintosh with an accelerated 3D 
graphics board and QuickDraw 3D 1.5.1 or better. 

If you wish to build an actual Cubby you need 
additional electronic hardware such as a head-tracker, three 
projectors and possibly extra graphics boards and scan 
conveners. As a head-tracker we use a Dynasight infra-red 
tracker by Origin Instruments. With regard to projectors, 
graphics boards and scan converters, your exact needs 
depend on which configuration you choose. We will discuss 
possible configurations in a minute. Of course, a Cubby 
consists of more than electronics and computer hardware 
alone. You also need to build a physical setup to position 
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the projectors relative to die screens. For quick 
experimentation you can build the display space using 
cardboard and tracing paper or drafting foil and mount the 
projectors on tripods providing they are not too big. Figure 
4 shows what our first setup looked like. For a more 
permanent and robust setup you need to build the display 
space from 1-5mm thick projection material (available from 
professional photography labs) and mount die projectors 
on a table (Figure 5). 



Figure 4 . Our preliminary setup with a display space 
hit lit from fact m boa rd a nd draft i ng fa it. The p rojec to rs 
are mounted on tripods. 



Figure 5. A more robust setup. This table makes it 
possible to accurately line up projectors and screens. 


Possible hardware configurations 

Your Mac: needs to generate three images, one per 
projection screen. You can these images to the three 
projectors in several ways. You can either work with one 
graphics board or three graphics boards and with either 


computer projectors or video projectors (A computer 
projector is a projector that can directly accept the VGA 
output of the graphics board of vour Mac; a video projector 
is one which only accepts a composite or S-video signal 
such as produced by your home video recorder. A projector 
which accepts VGA usually accepts S-video too, but not all 
video projectors accept VGA input). This leads to four 
possible configurations (Figure 6) 



Video 

Computer ■ 


Projection 

Projection 

One 

Graphics Board 

a 

b 

3 

cu 



s & 

h 

CL 

fS 

c 

d 

O 



Figure 6 . A 2x2 matrix leading to four 
different configurations. 
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Figure 7. The four different configuration a-tl 
(top to bottom) 
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FireWiseStuff 


The simplest configuration is to work with a single 
graphics board, use a multiplier to split the signal of this 
board into three identical signals, and feed each of these 
identical signals to a computer heartier (Figure 7a). Each 
projector is [dated in such a way relative to its screen that 
the relevant part of the image appears on the screen, while 
the two remaining images are simply discarded by being 
projected off screen. 

The second way is similar to the first, with the difference 
that we use a scan convener to convert the signal of the 
graphics board into a video signal, which is then split up by a 
video multiplier and fed to three video projectors (Figure 7b). 
While this results in lesser image quality it is likely to lie less 
expensive. The extra costs for the scan converter are less than 
the cost you save by using consumer grade video projectors 
instead of computer heamers. 

The disadvantage of using a single graphics board is that 
you do not make full use of the resolution of the projectors as 
approximately three quarters of the display area is discarded, 
A way to overcome this is to use three graphics boards instead 
of just one. Tills leads to a setup in which there is one 
graphics hoard per projector. Consequently, no splitter box is 
necessary. (Figure 7c). OF course, this assumes that your Mac 
has enough PCI slots free to add extra graphics boards. 

The last configuration is similar to the third, the 
difference being that it uses video projectors rather than 
computer projectors (Figure 7d), 

As always, there are clever ways to cut costs. For 
example, you can avoid the extra cost of one or more scan 
converters by using graphics boards which have both an 
output for a conventional monitor and a S-video output. 
Some desktop Macs and Power Books even have S-video 
outputs as part of their standard configuration. 

A Look at the Cubby Arp 

Before we dive into an explanation of the computer 
graphics behind Cubby, let's run the application to see what 
we are aiming fur. Don't worry about connecting a head- 
tracker to the Mac, for the moment we run under mouse 
control. Start up the application “Cubby 1 and open the model 
‘espresso. 5df, On screen you see an L-shape with an 
espresso pot (Figure 8), The L-shape comprises three 
QuickDraw 3D panes which are placed within a single 
window which covers the whole screen except for the menu 
bar (The advantage of using three panes within a single 
window instead of one window per view is that that the 
single window acts as a black backdrop to the panes. This 
prevents the Macintosh desktop from appearing at the outer 
edges of Cubby’s screens). While the espressopot was loaded 
from disk, the background planes with the marbled texture 
form part of the Cubby application. 

Now try moving the mouse. On the conventional 2D- 
monitor that you are using now, the three perspective views 
in the L-shape look strangely distorted. When the views are 
folded into a cube, as in Cubby's display space, and coupled 
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to Lhe user's head-position the espresso pot appears to stand 
within Cubby's space* 

Choose Mirrored from the images menu. This mirrors 
each image horizontally (Figure 9). By looking at the frames 
per second counter in the statusbar and choosing Normal and 
Mirrored repeatedly you can see how mirroring does not 
impose much of a speed penalty. 
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Figure & A screen shot of the Cubin' application 
(non mirrored A 



Multiple Head-Tracked Displays 

The easiest way to think of Cubby is as three head- 
tracked displays. Each of the back-projection screens is a 
head-trucked display. For an extensive discussion of head- 
tracked displays please refer to MacTedt July 1998 
(Djajadiningrat & Gribnau, 1998). In that issue we explained 
that for a head-tracked display an off-axis rather than an on- 
axis camera is needed In QuickDraw 3D speak this means a 
view plane camera rather than a aspect ratio camera. For 
Cubby we use three QuickDraw 3D views each of which has 
its own view plane camera. Each of the Figures 10 to 12 
shows one view plane camera, its coordinates, its viewing 
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pyramid and its line of sight, The point at which Cubby's 
three screens meet is placed at the origin of the world 
coordinate system. Notice how ihe three view plane cameras 
share the same location C with coordinates Cx, Cy and Cz, 
Later we will couple the camera's location to the head- 
position of the user. While the three cameras share the same 
location, each one has a different orientation as the line of 
sight of each camera is at right angles to its screen. The 
orientation of a view plane camera is determined by its 
location and the point of interest, point P in the figures. 
Figure 10 shows the camera for the screen in the Z=0 plane 
with the line of sight parallel to the z-axis Figure 11 shows 
the camera for the screen in the X=0 plane with the line of 
sigh! parallel ro the x-axis. Finally, Figure 12 shows the 
camera for the screen in the Y=0 plane with its line of sight 
parallel to the vertical y-axis. 




Figure IL The view plane camera for the X=Q plane. 



Mirroring without GWorlds 

To gel a convincing depth impression in Cubby the three 
screens need to form a single, seamless display. Therefore 
we cannot use conventional monitors or llat-panel displays, 
which always have a frame around their imageable area 
which would result in a disturbing seam (Figure 13) Instead 
we have to use projection screens. Since we are projecting 
on the back of the screens, we need to mirror the images that 
are sent to die projectors. So, how do we do this? Some 
projectors allow mirroring in hardware. But many projectors, 
especially the low-end ones, lack this feature which means 
that you have to mirror the images in software, Ihe 
conventional approach to software mirroring would go like 
this. First, we would render an image to an offscreen 
GWorld. Then we would need to copy this image to a second 
offscreen GWorld so that the image is mirrored. This could 
be done by copying the n-th one pixel-wide column of die 
first GWorld to the (widfh-n)th column of the second 
GWorld, Finally, we would copy ihis second GWorld to the 
screen, There are two problems with this approach. The first 
is that many graphics boards do not support hardware 
acceleration when rendering to offscreen GWorlds with 
QuickDraw 3D which would make rendering slow. The 
second is that the copying between the GWorlds takes too 
much time. And to gel a convincing depth impression with a 
head-tracked display we need all the speed we can gel. 


86 


Ci niiv: Mi in.M iii i N Dksktoi' VR Part I 


MACTKCH • Smt'MUKH 2000 





















FUNNELWEB 


f 1 ' Wi 


\ 


% 


V 




Better, Stronger, Faster 


Intelligent Web site Monitoring and Analysis Software 


Speed, intuitive user interface, accuracy and in-depth analysis have always made 
Funnel Web the intelligent choice for Web site analysis. 

Now includes pdf output, incremental analysis, cluster analysis and streaming media reports. 



Figure 13> We cannot use ordinary monitors to build 
Cubby's display space because of the borders around 
the imageable areas , 


Luckily, there is another way to mirror the images which 
does noL require offsc reen G Worlds. This involves mirroring the 
virtual scene, the lights and each camera to a different octant 
and reversing the orientation style of die scene. Remember that 
three-dimensional space is divided into eight octants by the 
three perpendicular coordinate planes. Figures 14 to 16 show 
the mirroring of the camera and the background planes (the 
mirroring of the rrnxlel and the lights is not shown). Each 


camera is mirrored in the plane for which it is intended, Let's 
consider each camera in turn. The original camera position is 
C, the mirrored position C. Figure I i shows how the camera 
for die Z=0 plane is mirrored in the- Z=0 plane. Figure 15 
shows how the camera for die X=0 plane is mirrored in the X=0 
plane. Finally, Figure 16 shows how die camera for the Y=0 
plane is mirrored in the Y=0 plane. Enough talk, let's look at 
the code, We split it up into two parts: the code concerning 
multiple views and the code for mirroring. 



Figure 14, Mirroring in the /~0 plane. 
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Figure 15* Mirroring in the X=0 plane. 



Figure 16 . Mirroring in the Y^Q plane. 


Multiple Views 

In iti is seel ion we discuss: 

• creating multiple views 

• adjusting the view plane cameras 

• submitting the views for rendering 

Creating multiple views 

So, how do we go about creating the three view's? We use 
a global struct gDoc of type DocumentRec with the fields IViewl, 
fView 2 and fVrew3 which contain pointers to the three views of 
Cubby. The DocumentRec struct is defined in Shell.h. You will 


see dial we use this struct a lot. it is a simple way of passing 
around often used variables such as view objects and matrices. 

From Init in Shell c (Listing 1) we call initDocumentData in 
(DeJInit.c. The global struct gDoc is passed as a pant meter. 

Listing 1: Shell.c _ 

init 

IriitDocuiaentData(4ftDoc, ^Window] : 

In InilDocumentData we fill in the fields fViewl, fView2 
and fView3 of the ioDoe parameter by calling newView in 
ViewCreation.c ihree times and passing the rectangles of the 
panes within our window (Listing 2), 

Listing 2: (l)e)Init,c 

I nitDocumcnilI h x:itm trn I Ptr it>1 )oc . Windo wPr r in Win dow) 

Rect theRectl=[kPane!T r kFanelL. kPanatB, kPanelRh 
Rect theRect2“lkPane2T, kPane2L, kPano^B* kPane^Rl: 

Reel thfcReet^lkPafteST. kPano3L. kParielB, kPane3R); 

iutkic >fViewl-newView(ioDoc * InWindov, StheRectl) : 

> fView2~newView (loDoc, inWindow. &theRect2): 
iottoc- y fView3-nevViev tioBoc. intfindov, itheRecti): 

The routine newView should need further explanation 
as it forms a standard part of each QuickDraw 3D 
application. It calls newDrawContext and passes in a rectangle 
to set up a pane within a window (Listing 3T 

l isting 3: View Creation, c 

newDrawCcmtext (WlmJowPtr In Window, Rett 'inRect) 

thfiDrawContextData.paneState = kQ3True: 
theDrawContextDars.panfi.EiI ti.x - 1 nRfict >left: 
theDrawContfixtDiUa.pane.Enin.y ” InRect Hop: 
t henrawContejit0ata*pat3c*nwix*x - inJLeet - >right; 

l het! r a wCon text Data, pane, max. y “ inRect ->bottoa; 

The routine newDrawContext returns a new draw context 
lo newView. It then goes on U> create and set a rendered a 
view plane camera and a light group. As you can see, 
creating multiple views is quite simple. It is a matter of 
repeating the view object creation as found in each basic 
QuickDraw 3D application. 

Adjusting the three view plane cameras 

Now we come to the most interesting part of the code: 
adjusting the view plane camera of each view to the current 
position of the head-tracker (Lisiing 4), We need to convert 
the raw head-position, expressed in the head-trackers own 
coordinate system, to the world coordinate system. This is 
done by calling Q3Poinl3D_Jranslurm with the calibration 
matrix in the fCalMatrix field of our struct gDoc which was 
passed as a parameter to AdjustCameras. We will discuss 
how to create Lhis matrix in the third part of this series. 

Once we have a camera position in world coordinates, 
we need to ascertain that it stays within the positive XYZ 
octant. Just before the camera threatens to move outside this 
octant, the camera's hither plane is pushed through the 
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background plane causing the latter to disappear. This is a 
disturbing effect which we can avoid by carefully tuning the 
minimum allowed distance between camera and background 
plane to the hither value of the camera. Here we set the 
minimum allowed distance between camera and background 
plane to kHitfter4kMargin QuickDraw 30 units, A user of 
Cubby who comes closer to the screens than the real world 
equivalent of kHither+kMargin QuickDraw 3D units will 
notice that the perspectives do not completely follow his 
head movements, bin at least the background plane on that 
screen docs not completely disappear In the section Tidbits 
we discuss a more elegant way to solve this problem. 

AdjuslCamems finishes by calling AdjustOneCamera for 
each view and passing the camera position as a parameter. 


Listing 4s ViewPlaneCamcra,c_ 

AdjustCnmens 

TQ3Point3D H. C: 

// apply the calibration matrix to convert the 
// raw head position to a earner? position 
// in world coordinates. 

G3PqiriL3D_Transforin(&H, 

&lnl)uc > fCa1 HatrIx * 
kC)t 

// Limit die camera position so 
// we do not move beyond die screens 

if (G.x<= kHither) C.x“ kHither ; 

iT (C.y<" kHither) C.y“ kHither : 

if (C.z<- kHither) C.z- kHither : 

// Adjust ihe camera of each view, 

AdjustOneCfl]netti(iriboe, &C. kViowl): 

AdjusiGneCamera{inboe. &C, kViett2); 

AdjustOneCameraUnDoe , &C, kVievl): 

return kQ35uccess ; 

bail: 

return kQ3Fai1ure t 


Let’s look at AdjustOneCamera (Listing 6). In this routine we 
adjust a view plane camera of a single view by getting the 
camera object from the view and updating its parameters. Our 
objective is to be able to till in the TQSViewPlaneCameraData 
struct as defined in QD3DCannera.h (Listing 5). This means that 
we also need Lo be able to fill in a TQ3CameraData struct, a 
TQ3CameraP!acement struct and a TG3CameraRange struct 
Luckily, some variables do not change as we adjust our cameras. 
The halfWidthAtViewPlane, halfHeightAtViewPJane and viewport 
variables stay the same during the execution of our program. 


Listing 5 

struct TQ3VievPlaneCameraData I 
TQ3Came ratters eameraEteta; 

float vicwPlane: 

float lial f Hid iMtV S ewPlane: 

float halftlei^htAtVieiifriane; 

float centerXOnViewPlane; 

float eenterYQnViewFiane; 

I; 


strtid TGlCamfi rafter, a t 

TQSCatner a Placement placement; 


TQ 3 C a me r a R a n g e ran ge: 

TG3 CaMeraVievPor t vievPo r t; 

1 ; 

struct TQ3CameraPlacement I 

TQ3Point3D c a up raLocation: TQ3Foint3D 

pointOfInterest: 

TQ3Vector3D upVecUr: 

I; 

struct TQ3CanieraRai , i£e I 

float hither: 

float yonj 

); 


We start by setting the camera location C to a local copy 
of the camera location parameter inC that was passed to 
AdjustOneCamera. We also set the point of interest to the inC 
parameter (Notice that the term point of interest is somewhat 
misleading. The point of interest is the direction in which the 
camera is pointing but with a view plane camera it need not 
be visible as part of our image). 

The next thing Ls to determine which view we are 
dealing wilh. We do this through a switch statement which 
looks at the inViewNumber parameter. In each case of the 
switch statement we get the camera object from the view, 
adjust the point of interest P, and set the distance to the view 
plane. We discuss the cases one by one. 

If the inViewNumber equals kViewl, we are dealing with the 
View on the ZK) plane (Figure 14). First we get the camera 
object from the view by culling Q3View_GelCamera. As the point 
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of interest for the camera of this view is the projection of the 
camera location on the Z=0 plane, we set P,z to zero. To dcscril)e 
the settings of a view plane camera we also need the distance 
from the camera to the view plane, held in theViewPlane variable. 
The camera for kViewl ltK>ks parallel to the Z-axis so the distance 
equals the ^-coordinate of the camera location. 

If the inViewNumber equals kViewZ* we are dealing with 
the view on the X^fl plane (Figure 15). Again we start by 
getting the camera object from the view by calling 
Q3View_GetCamera, As the point of interest for the camera of 
this view is the projection of the camera location on the X=0 
plane, we set P.x to zero* The camera for kView2 looks 
parallel to the X-axis so the distance from the camera to the 
view plane equals the x-coofdinate of the camera location* 

Finally, if the inViewMumber equals kView3. w r e are 
dealing w ith the view on the Y=0 plane i Figure 16). Again we 
start by getting ihe camera object from the view by calling 
G3ViewJ3etCamera. As the point of interest for the camera of 
tills view 7 is the projection of the camera location on the Y=0 
plane, we set P.y to zero* Ihe camera for kView3 looks parallel 
to the Y-axis so the distance from the camera to the view plane 
equals the y-coordinate of the camera location. With this view 
we need to take care of one more thing. As the camera is 
looking down on the Y=0 plane as if it w r ere a photographic 
enlarger, we need to change the up vector of the camera from 
(0,1,0) to (0 P 0 T d). The up vector for this views camera points 
in the direction of the negative z-axis. 

Now we need to look at die centerXOnViewPlane and the 
centerYOnViewPlane settings of the view plane camera. These 
determine the centre of the part of the view plane that we 
are interested in, indicated by an Q in Figures 14 to 16. In 
world coordinates point Q does not change, but as 
centerXQnViewPlane and centerYOnViewPlane are expressed in 
the camera’s coordinate system they need to lie adjusted if 
the camera is moved (For the moment we only consider non- 
mirrored cameras, later we will discuss what happens w hen 
we mirror the cameras* So we ignore the if (IgMirrored) 
statements for the moment and return to those later. )* 

CenterXOnViewPlane is the x-coordmate of the 
projection of the vector PY on the view- plane in terms of 
camera's coordinate system, Likewise, CenterYOnViewPlane is 
the y-coordinate of the projection of the vector PY on the 
view plane in terms of camera’s coordinate system. Let’s look 
at CentefXOnViewPlane and CenterYOnViewPlane for each of 
the three views. 

Figure 14 shows that for kViewl, looking at the plane Z=0: 

theCenterX = -C.x + kHalfWidthAtViewPlane; 
theCenterY * C.y + kHalfWidthAtViewPiane: 

In Listing 6 the code says: 

theCenterX - -C.x + MalfWidthAtVic^Plane + kfO; 
theCenterY « Q.y + kHalfWldthALVievPlane + kFO: 

So what is this mysterious kFO? Well, tliis is a Fiddle Offset 
constant* If you ltx>k in ihe header MyDefines.h you wall see that 


it equals 0,00 i. Set it to 0, compile and run the Cubby app. You 
will see that suddenly the backgrounds start to flicker. 
Obviously, QuickDraw 3D is not very happy if the point of 
interest is a perfect projection on the view plane and it has to 
render polygons which lie exactly in the view plane. This is 
why we added ihe Fiddle Offset. kFO is so small dial it does not 
cause any distortion but ii does get rid of the flickering. 

Figure 15 shows that for kVievv2. looking at the plane X=Q; 

theCenierX - +C. z - kHalfWidthAtViewPlarie + kFO: 
theCenterY = C.y « kHal fWidtMlViewPlane + kFO; 

Finally, Figure 1.6 tells us that for kVicwJ, looking at the 
plane Y-0: 

theCenterX - C.x + kHalfWidthAtVievPlane + kFO; 
theCenterY - +C*z kiUlfWidthAtViewPiane * kFO; 

The last variables that we have to adjust are the hither 
and yon planes. Remember that we set a minimum distance 
of RHither+kMargin QuickDraw 30 units for the camera to 
approach the X=0 f Y-0 and Z=0 planes* Here you see what 
the kMargin constant is good for: we avoid pushing the hither 
plane through the background planes by a margin of 
kMargin. A background plane is not only dipped if it lies 
between the camera location and the hither plane, but also ii 
it lies beyond the yon plane. We prevent this from happening 
by setting the yon value io the view plane distance plus 
kMargin QuickDraw 31 > units. 

We complete the routine AdjustGneCamera by disposing 
the camera object through GSGbjectJDispose to balance the 
reference count. 


Listing 6: VicwIMancCamcra.c 

Adjust QntCamerj 


void Ad justOneCa roc ra t Document Ftr iuDoc. 

TQ3Point3D *inC, 
short inViewNumber) 


I 


TQ 3 Came raO b j ec t t h eCaaie r a : 

TQ3CameraPIacement theCameraPlacement; 


TQ3Fcdnt3D 
TQ3VectQt:3D 
float 
float 
float 

TQ3CameraRange 


C, P; 

fhetjp * i 0.0, 

iheViewPlane: 

theCenterX: 

theCenterY: 

theRange; 


1.0, 0.0 h 


// Make a local copy of the camera location. 
Q3Point3D„Set UC* inC~>x. inC>y t inC >z)\ 

// Determine the point of interest 
// Ii Is derived from the camera location* 

// so start with a copy of the camera location. 

Q3Point3DJ>et UP, iliC->x* inCDy. inC>zh 

switch (inViewNumber) 

\ 

case kViewl: 


// Get the camera from the view 

G3ViE!w_Get Conner a [ inDoc ’ JfViewl, AtheCataera): 

P.x - 0*0; 
theViewPlane - C.z; 


break; 
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case kViev2; 

// Get Uir camera from the view 

Q3View GetCamera(inDoc->fView2 r AtheCamera): 

P.X - 0,0; 
theViewPlane ” C.x; 

break: 

case kViev3; 


// Get the camera from the view 

Q3View_GetCamera(inDoc->fView3, ktheCamera): 

P,y - 0,0; 
theViewPlane s C.y; 

// As this camera is pointing parallel to 

//the Y-axis, we need to change the LhcUp vector 

Q3Vector3D_Set UtheUp. 0, 0, 1); 

break; 
l 

if UgMirrored) 

i 

switch (inVievNumber) 

I 

case kViewi; 

theCenterX - C.x + kHalfWidthAtViewPlane + kFO; 

theCenterY - C.y + kHalfWidthAtViewPlane + kFO; 

break; 

case kView2: 

theCenterX - +C.z - kHalFWidthAtVievFlane + kFO: 

theCenterY “ -C.y + kHalfWidthAtViewFlane + kFO; 

break; 

case kView3; 

TheCenterX - -C.x + kHalfWidthAtViewPlane + kFO; 

theCenterY - +C.z - kHalfWidthAtViewPlane + kFO; 

break; 

I 

I 

else 

( 

switch (inViewNutnber) 

l 

case kViewi; 

// Mirror in 2=0 plane, 

C + z a *C*z; 

theCenterX - +C.x - kHalfWidthAtViewPlane + kFO; 

theCenterY * C.y + kHalfWidthAtViewPlane + kFO; 
break: 

case kView2: 

// Mirror in X=0 plane. 

C.x - -C.x: 

theCenterX ■* -C,z + kHalfWidthAtViewPlane + kFO; 
theCenterY - C,y + kHalfWidthAtViewPlane + kFO: 
break: 

case fcView3; 

// Mirror in Y=0 plane 
C.y * *C.y: 

theCenterX - +C.x - kHalfWidthAtViewPlane 4 kFO; 
theCenterY - +C.z - kHalfWidthAtViewPlane + kFO: 
break; 

f 


// Adjust the hither and yon planes 
theRange.hither" kHither; 
theRange.yon - theViewPHne 4 kMargin; 


// Fill in the camera placement. 

theCameraPlacement,cameraLocation C; 
theCameraPlacement. pointOf Interest ■ P; 

theCameraPlacement.upVector = theUp; 

// Fill in the Gelds of the camera 

Q3Camera„SetPlaceBient (theCamera. &theCameraFlacement): 
Q3ViewFlaneCaiuer3_SetViewFlane [theCamera, theViewPlane); 
G3VievPlaneCamera_SetCenterX (theCamera, theCenterX): 
Q3VievFlaneCantera_SetCenterY (theCamera, theCenterY); 
Q3Camera„£etRange(theCaiHera* &theRange); 

// Dispose of rhe camera object 

Q30bject_Dispose{ theCamera ) : 


Submitting three views for rendering 

Now that we have adjusted the view plane camera of all 
three views, we can submit the views for rendering. Have a look 
ai Listing 7 which shows the routine DocumentDraw3DData, The 
routine starts by calling Q3View_Sync for all ihree views. This is 
to force all three views to finish rendering the previous frame 
before we start rendering the next one. Again we ignore the if 
(gMtrrored) statements for the moment. The remaining part of 
DocumenlDrawSDdata calls SubmttOneView in a rendering loop 
for each of the three views. 


Listing 7: Renderings_ 

D< k: umtn tDrawi D Data 

TQ3 Status SubmitViews ( DocumentPtr inDoc } 

( 

TQ3Status theStatus ; 

Q3Viev_J>ync(inDoc->fView1); 

G3View_Sync(inDoc->fView2); 

Q3View_5ync £inDoc->fViev3); 


if [gMlrrored) 

inDoc-> fHirrorMatrix = inDoc XfMatrixMrrorZO; 


//The rendering loop for fVicwl 
Q3View_StartRendering( inDoc->fVievl ); 
do 

r 

theStatus - SubmitOneVlevf InDoc, fc (inDoc >fViewl)); 

f 

while ( Q3View_J£ndRendering( inDoc >fViewl) 

= kQiViewStatusRetraverse ): 


if (gMirrored) 

inDoc) fMirrorWatrix = inDoc->fMatrixMitrorX0; 


//The rendering loop for fVicw2 

Q3View_StartRendering! inDoc->fViev2 }; 

do 

I 

theStatus “ SubmitOneView(inDoc. i(inDoc->fVlew2J); 
I 

while [ Q3Viev EndRendering!inDoc->fView2) 

— kQSViewStatusRet raverne ); 

if (gHirrored) 

inDoc) fHirrorMatrix — inDoc->fMatrixMirrerYU: 


//The rendering loop for fVicw3 

Q3Viev_StartRendering! inDoc->fViev3 ); 
do 
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theStatus - SubmitQneVievjinDoc. &(inDoc->fView3 ))t 

I 

while ( Q3Viev_Erid Rend e ring E IriDoc >fView3) 

«« kQ3View5tatiisRetraverse ); 

return theStatus ; 

i 
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So we turn our attention to SubmitOneView (Listing 8) 
which, you guessed it, submits a single view for rendering. 
Again we ignore the if(gMirrored) statement for the moment. 
The most important aspect of this routine is that we first 
submit the display group fDisplaySpace which contains the 
background planes, then the shader object and finally the 
model which was loaded from disk. If we would submit the 
background planes after the shading object Lhe lighting on 
the background planes would change with the user's head- 
position. By submitting the background planes first we avoid 
getting such disturbing shading effects. The model which 
was loaded from disk is shaded as normal as it is submitted 
after the shading object. 


Listing 8: Renderings 

SubmiiOncVicw 

TQ3Siatus SubmitOneView[ DocumentPtr inDoc, 

TQ3View0bject inView) 

I 

// if wl- wish to mirror the image, wc need 
// to submit .t mirroring matrix and change 
// the orientation style from counter clockwise 
// to clockwise 

if (gMirrored) 

I 

Q3MaLrixTransforni_Submit ( &inDoc~> fMirr or Matrix* 

inView) ; 

UJ Sty1e_Submit(inDoc * >fOrientationStyle. 


£}3$tyle Submit 11 nT>oc >fInterpolation, inView); 

Q3Style_Submil{inDoc >fBackFncing, inView); 

Q3 St y1e_Subei t (InDoc - >f FillSty ie. inView): 

ft submit the background planes which form 
tt the cubic display space before we submit 
it the shader.Thai way we get evenly lit 
It background planes* regardless of where the 
// cameras are, 

Q3DlsplayGrmip_SuhmU E InDoc HMsplaySpace * inView); 
tt submit shader and styles 

Q35hadur_Submit(inDocIIlurainationShader. inView); 
tt fit the model to the cubic display space 

Q3MatrixTransform Submit (&lnDoc->fModelHatriiL, inView); 

ft submit the model which was loaded from disk 

Q3DisplayGroup_Submit( inDoc->FModel, inView): 

return kQ3Suecess ; 

J 


Mirroring the Views 

If your projectors do not feature hardware mirroring* 
you have to mirror the images in software. Perfect mirroring 
not only requires mirroring the camera and the virtual scene 
(including the background planes), but also mirroring the 
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lights :md changing ihc orientation style. The order in which 
we discuss things is: 

• creating the mirroring matrices 

• setting the mirroring global 

• mirroring the lights 

• mirroring the three view plane cameras 

• mirroring the virtual scene 

■ adjusting the orientation style 

Creating the mirroring matrices 

As we saw at the beginning of this article we need to do 
mirroring in the X=0, Y=0 and Z=0 planes* Listing 9 shows a 
code snippet for creating the three matrices that we need for 
these mirroring operations* 

Listing 9 (De)Init t c 

Initltoc iimc ntOata 

QBMatrix4x4„SetSeatc(&ioDoc->fMatrlxHirrorXQ. -1, 1, 1); 

(}3Mat rix4x4_5et Scale (kioDoc >THatrixMtrrorYO, l* 1* 1); 
Q3Matrix4x4_SeiSeaIe(&ioDoc >THaLrixMirrorZG, E* l» ~i); 

We use the QuickDraw 3f) routine Q3Malrix4x4_SetScale to 
create each matrix* Scaling by -1 along one axis results in 
mirroring in the perpendicular plane. For example, scaling by -1 
in along the x-axis results in mirroring in the plane X=0. 

Setting the mirroring global 

Next we kx>k what happens when the user chooses Normal or 
Mirrored from the Images menu. Menu interaction is handled by the 
routine DoMenuCommand in Shell.c. Listing 10 shows an excerpt for 
the images menu. First HandloMenuCheckedltem is called which 
handles the checkmark in from of the menu items. Then die 
Ixxjlcan gMirrored is toggled which determines whether to mirror 
the images or not Finally, we call the routine mirrorLights for each 
view and pass the appropriate mirroring matrix as a parameter* 

Listing 10 SlielLc 

E>o Men uComma nd 

case mlmages; 
switch (item) 

I 

case iNormali 


Mirroring the lights 

We need to make sure that we mirror all the ligliLs that 
belting to a view. When we created the view (newView in 
ViewCreation.c) we put all the lights in a light group object. 
What we have to do now is to obtain the light group from 
the view* traverse the light group, determine the type of each 
light and mirror the aspects relevant to that light. This is 
detailed in Listing 11. 

We use the QuickDraw 3D routine Q3Light_GetType to 
determine the type of light. Through a switch statement we 
get cases for all possible types of light: ambient lights, point 
lights, directional lights and spot lights. An ambient light 
needs no mirroring as it has neither a location nor a 
direction* A point light has a location but no direction so we 
only need to mirror the former. A directional light can be 
thought of as the opposite of a point light: it has no location 
but it does have a direction so we only need to mirror the 
latter. Finally, there are spot lights which have both a 
location and a direction, so we need to mirror both. 


Listing 11 MirrorLighls.c 

mirrorLights 


TQJStatus mirrorLights(TQ3View0bject 
TQ3Matrix4x4 


i 


InVlcWp 

iriMatrix] 


TQ3GroupQbject 
TQlGroupPosition 
TCtf Object 
TQ3Stalus 
TQ3GbjectType 
TQ3Point3D 
TQ3Vector30 


t heGroup ; // the v Lew's light group 

t h e P o e : If a ga>up pos i i ion 

theLight; //u light 

theReeult: // :i result axle 
theType; 
theLoe; 
theDir; 


// (let the light group from the view. 

iheResul \ ~ Q3Vfpw_Get.LfghtGrmip (inView. ktheGroup): 
iE (ihcResuli kG3Fai1uro) goto bail; 

//Traverse ihe light group and mirror the positions 
//and di reckons of alt light types as needed. 

for f QJGroup.GetFirstPositionttheGroup, bthePos}; 
thePos != NULL: 

Q3Group_GetNextPosition ftheGroup, SthePos)) 

1 

iheRestill ” Q3Group_Get Posit iotlGbject[thefiroup, 

thePos, 
itheLight); 

if (theResult ™ kQ3Fai1ure) goto ball: 
theType = fj3Light_CetType(theLight); 


if (gMirrored " true) 
f 

Ha nd1eMe nuUhe ekydltern(iiem); 
gMirrored = false: 

airrorLights(gDoc*fViewl* gDoc.fMatrixMirrorZO); 
mirrorLightfi(g0oe*fView2. &Doc« fMatrixMirrorXOj; 
mlr rorLlghtn(gDoe*fViev3* gDoc,fMatrixMirrorYO); 

1 

break; 

ease iHirrored; 

if (gKirrored *“ false) 

f 

Hand leMnnuChec kedltent {item) ; 
gMirrored = true; 

mirrorLighta(gDoc. ftfievt, gDoc*fKatrixMirrorZO); 
mi rrorLEghtfi(gDoc.fViev2, gDoc.fHatrixMirrorXO); 
tnirrorUghts CgDoc. fView3 „ gDoe* fMarrixKi rrorYG); 
I 

break: 


N What we mirror depends on the type of light, 
switch {theType) 

I 

case kQ3LightTypeAmhient: break; 

case kQ3Light r fypePoinl; 

Q3FointLight_GetLocation(theLight * irtheLoc); 
Q3Point3D_Transforni(&theLpc* &inMatrix, btheLoc); 
Q3PointLight_SeiLocation(theLight, &rheLoc); 
break; 

case kQ3LightTypefi1rectional: 

Q3DirectionaLLight_GetlHteclion (LheLi ght * &thp_Dir): 
G3Vector3D_Trans form(it heDir, 

GrinKatrix* 
itheOir): 

03DirectionaiLight_SetDirection(theLight* itheDir); 
break; 
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case kQSLightTypeSpot- 

Q3Spr>t:t< i ght_GctLocation £ thelight. ktheLoe): 
Q3Poini3D_Ttimsforia(4theLoc P iinMatrix, &rheLoc): 
Q3SpotLight JSetLocation { theLight* fctheLoe); 

U3SpotLight_CetDirection(theLiglit, itheDir); 

Q3 V e c 1 0 r 3 D_T r an sf 0 nn ( &theDi t * 
iinHatrijt. 

&tfreDir); 

Q3SpotLight_SetDirection(theLigbt, itheDir); 
break; 

1 

// balance reference o>uni of tight 
Q30b}ect_Dispoee(theLight); 


Q3Gbject Dispone(tbeGroUp) ; 
return(kQ3Success); 
ball; 

return £kQ3Failure); 

1 


Mirroring the three view plane cameras 

We now return to Listing 6 AdjustOneCamera to look 
what happens if wc wish to mirror the cameras, look for the 
ebe-branch of the conditional statement rf(!gMirrored). First 
we determine which of the three views we are dealing w r ith. 
Then we mirror the location of the camera and adjust the 
CenterXOnViewPlane and CenterYOnViewPlane variables. By 


now you should be able to relate this code to the mirrored 
cameras in Figures 14 to 16. 

Mirroring the virtual scene 

Of course we also need to mirror the model which we 
loaded from disk and the background planes. Look at the 
conditional statements if(g Mirrored) in Submit Views in 
Renderings. Just before we call SubmitOneView for each 
view, wc set the field fMiuorMatnx of the struct gDoc to the 
mirroring matrix for that view. In SubmitOneView we .submit 
the matrix in the fMirrorMatrix field before anything else. This 
is what mirrors the background planes and the model 

Adjusting the orientation style 

Think about what we did when we did our mirroring. We 
mirrored our model so we mirrored its polygons and its vertices. 
That means we reversed the direction in which the vertices of a 
polygon are listed. This is important as the direction in which the 
vertices of a polygon are listed determines which side of die 
polygon is considered as the front lace which in turn influences 
shading. We can diangc w hat QuickDraw 3D considers to be the 
front Lice by changing the orientation style. The default is 
kQ30nentatEonStyleCounterC!ockwse, which means that the front 
face Is the side from which the vertices are listed counterclockwise. 
By changing the orientation style to kOSOrientatronStyleClockwise 
the front and hack face are Hipped, this is what happens in Listing 
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8, SubmitOneView in Rendering.c, Notice that we do not explicitly 
toggle between kQ30rienlalionSlyteCounterClockwise and 
kQ30nentatk)nStyleClockwise, In non-mirrorcd inode we simply rely 
on tlie default Only in the mirrored mode do we actually submit 
an orientation style using Q30rientalionStyle_Submit. The style is 
created in InitDocumentData in (De)lnit.c through the call 
G30rientationStyle_New (Listing 12). You may wish to read up on 
the orientation style object in the QuickDraw 3D 15.4 manual 
(Chapter 6, page 550). 

lasting 12 (DcJInlU 

JnitnocumcntDaia 

ioDoc’>fOrisntationStyle « 

Q10rient3tionStyle_Naw(kQ30rientatiQnStyleCiockwise); 


T ROUBLESHOOTING 

Make sure you have a kx>k at the troubleshooting 
sections of our previous articles in MacTedi July 1998 and 
August 1998. In addition, have a look whether your 
problem is among these. 

One of the background planes remains untextured 

Explanation: You may have run out of VRAM, 
Running in a high resolution (say 1024x768 or above), in 
millions of colours and a couple of textures may simply 
be too much for the VRAM of your graphics board, 
especially if it has only 1MB or 8MB. 

SoluUon: Try running in thousands rather than 
millions of colours, reduce the sizes of your textures or 
Lise fewer textures. If these solutions are out of the 
question, consider a graphics board with more VRAM 

Tidbits 

As always there are ways to improve the code. Here 
are some things you may wish to Ux>k at. 

Delays between views 

In the MacTech article on single screen head-tracked 
displays we mentioned the problem caused by delay: the 
perspective shown on the screen does not correspond to 
the head position of the user, causing the virtual scene to 
appear distorted. Cubby’s three views cause an additional 
delay related problem. Because the three views do not 
render equally fast, we can get discontinuities on the edge 
of two views. This effect become particularly noticeable 
under quick camera movements. One way to eliminate this 
problem would be to use a TQ3PixmapDrawContext. Ml 
three views are rendered to an offscreen GWorld and copy 
this GWorld to the screen. The awkward thing is that not all 
3I> graphics boards support accelerated rendering to 
offscreen GWorlds. For graphics accelerators by ATI you 
can get code from All developer support which makes 
accelerated offscreen rendering possible. 


Limiting the camera position 

We discussed the problem that we had with the hither 
plane of a camera being pushed through the background 
planes, causing the latter to disappear. Just as the delays 
between the views, this can be fixed by using a 
TQ3PixmapDrawContexr. A 2D background texture is copied 
to a Gworld which is used as the pixmap. The virtual scene 
is rendered over this background texture. So instead of 
making the background planes part of the virtual scene, the 
background planes are a simple 2D background texture. 

Conclusions 

By now you should have a good idea of how the 
visualization part of Cubby works. You learnt how to 
configure three views with view plane cameras. You also 
learnt how to mirror the resulting images. But before you can 
enjoy a virtual scene in Cubby there's some more work to do. 
You need to know how to build an InputSprocket driver and 
how to calibrate the head-tracker so that the user’s head 
movements give the correct perspectives in Cubby. Tune in 
next month and we’ll show you how. 
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PDF and XML 


List month we covered Adobe s Portable Document 
Format (PDF), focusing on how it relates to Quarry 
Apple's new imaging model. Jn brief, PDF originated as a 
simplif ication of PostScript, retaining PostScript's primitive 
graphics operators while discarding its programming- 
language constructs and adding file and document 
structure specifications. Quartz (specifically, the Core 
Graphics Rendering API) is again based on this same set 
of operators, making it natural to “record” graphics 
operations into a PDF file, and just as natural to “play 
back" a PDF into a series of native drawing instructions. 
At its simplest, PDF is the new PICT; more interestingly, 
the Quartz imaging model is at the center of all 21> 
graphics on Mac OS X, providing a centralized facility for 
rending drawing commands from different APIs (such as 
QuickDraw) into different output formats, be they 
destined for the screen, a printer, or a file. 

Of course, part of the beauty of Quartz is that it frees 
the programmer from having to worry about the details of 
this process. At the same time, Quartz is certain to increase 
the popularity of PDF. and in particular expand its use 
beyond just a format for traditional documents. 
Accordingly, it will be to a programmers advantage to 
know as much as possible about PDF, and to be aware of 
its strengths and its weaknesses. 

As touched on above, PDF defines a file formal in 
addition ro a graphics model. In the abstract, a PDF file 
describes a tree of objects, with a significant separation 
between document content and document layout. This 
should send off bells in a developer s head, because it 
sounds similar to XML, and it's natural to wonder how 
deep this connection is—to ask questions like, “can a PDF 
document be represented in XML.* The short answer is 
“probably not\ but it’s interesting to investigate the 
parallels between the two formats. 

Intersections with XML 

PDF and XML are similar in that they define a file 
structure which is designed to encapsulate a wide range of 
data in a fairly generalized, hierarchical fashion. Although 
PDF is designed to be extensible, it does define an 
interpretation for the information it contains, and it s noi 


dear how well current PDF-rendering applications would 
handle PDF documents with content which they don’t 
recognize, XML is at the other extreme. At its core, it says 
nothing about the semantics of the data which it can 
contain, and it's often used as a format for information 
which isn i naturally thought of as a “document*” Bui given 
its generality; it would certainly be possible to devise an 
XML-based format to encapsulate page-descriptions in a 
manner similar Lo PDF, On the oilier hand, there are several 
facilities of PDF which are not easily mimicked using 
XML—features dealing more with practical performance 
issues than with conceptual structure. 

PDF was designed to be a final format, so that PDFs 
represent finished documents, rather than in-progress 
works (such as word processing documents) which will be 
extensively changed. Still, it is possible to make limited 
modifications to PDF's, and interestingly this can be done 
by appending the "change" information to the end of a 
PDF, without requiring the entire document to be rewritten. 
This makes it convenient to prepare an initial document 
and at a later stage add annotations or hyperlinks. This 
approach also provides a measure of safety, as previous 
versions of a document can be recovered simply by 
truncating the changes off the end, and modifications 
cannot cause complete corruption of the base document. 
This also means that it is possible to modify large 
documents without large resource requirements. 

Despite XMLs flexibility, it isn’t possible to create a 
well-formed XML document by appending information 
directly to another document, because of the requirement 
that there be a single root element. (It is possible to work 
around Lhis limitation, but only by splitting the document 
into multiple files,) Additionally, PDF documents 
frequently encapsulate binary data (such as images or 
compressed lexL), and it is not convenient to embed such 
data into XML documents directly-—XML is a text based 
format, and binary data could lx* -interpreted as markup, 
or mangled if the document is converted to a different 
character encoding. XML-based formats traditionally 
handle this by storing the data in a separate file which is 
then referenced from the base document, just as images 
are included in HTML files. This is less convenient than 
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PDF's single-file approach. (It would he possible to 
include binary da La in XML documents by convening it 
into a text-based representation, such as Base-64 
encoding, but this tends ter offset the benefits of 
compressionJ Finally, PDF has a higher structural 
flexibility, in that logical containment is not always 
represented by physical containment. In other words, 
structures which logically contain other objects may do so 
by referencing the objects by name, whereas in XML such 
containment is almost always represented by physically 
nesting elements. This flexibility allows the same PDF to 
be represented in different ways, so that for example a 
PDF file may be optimized for page-at-a-time delivery 
over the internet, or alternatively it could be created in a 
single-pass by a printer driver. 

FOP 

So despite the current popularity of XML, it ism likely 
that PDF is going to be superceded any time soon. So where 
do PDF and XML intersect? Well, as we observed before, it's 
naLural to think of XML as unformatted data, and to think of 
PDF as an output format. The preferred way to get from XML 
to something with formatting is by way of XSL 
Transformations (XSLTL In the case of XML-to-PDF 
transformation, there s a tool to help with the process. FOP. 
(IPs part of the Apache XML project.) To use FOP, you first 
use an X.SI.T processor to convert your XML document into a 
tree of formatting objects, which may itself be represented as 
an XML document. This is where you determine the form of 
your final document. Since, as mentioned above, XML 
documents are traditionally devoid of formatting information 
and are often viewed as pure data, any decisions about how 
I his information will be presented must be encapsulated in 


the style sheet. Once this is done, and you have your tree of 
formatting objects; you feed this into FOP. which produces 
your final PDF. FOP Is very much a work in progress, and 
does not yet support all of the formatting objects defined in 
the XSL specification, but even as is it appears quite useful. 
IBM has an informative tutorial on transforming XML 
documents. (A free registration is required to access the 
tutorial,) It discusses using FOP to create PDF documents, 
and in addition shows you how to generate SVG (Scalable 
Vector Graphics), which is useful for creating things like 
charts and graphs from XML encapsulated data. 

FOP 

<http://xml. apache.org/fop/> 

Tutorial: Transforming XML documents 

<http://wwwjbm.com/software/devebper/educationytransforming-xml/> 

OmniPDF 

Finally, while you’re playing with PDF. he sure to check 
out Omni PDF if you are running Mac OS X, Its a very cool 
PDF viewer, IDs still under development, but it's Cocoa- 
native (and hence Mae-OS-X-mitiveh and it really shows off 
the power of Quartz, as it uses Core Graphics Kendering to 
do its magic. (OmniPDF is from the Omni Group, who also 
created OmntWeb, which is currently the only Cocoa-native 
web browser available. You should check it out also—it's a 
refreshing alternative, and it has many fun features which set 
it apart from your usual browser choices.) 

OmniPDF 

<http://www.omnigfoup.com/products/omnipdf/> 

OmniWeb 

<http://www,omntgroup,com/produc.ts/omniweb/> (HQ 


Fight Boredom 

Lei’s face it: Much of programming is boring 
and repetitive. Well, that’s where the right 
tool can save days, weeks, or even months 
of your valuable time, 



Model- View-Controller 

AppMaker’s generated code uses the MVC 
paradigm. It separates the user interface 
from application logic, making code easier 
to write. You deal only with abstract data; 
AppMaker takes care of the user interface. 


AppMaker 

Your Assistant Programmer 

AppMaker makes it faster and easier to make an 
application. It’s like having your own assistant 
programmer. You point and click to tell 
AppMaker the results you want, then it 
generates “human, professional quality code" 
to implement your design. 


Scriptable Applications 

AppMaker generates the 'aete' resource and 
generates code to access your data 
(Properties and Elements in the Apple Event 
Object Model) and to handle Events. 

Just $199 from www.devdepot.com B*0*W*L*R*S 
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Getting Started with Perl 


Open Source power 
scripting for Macs. 


Introduction 

Perl is a prognmiming/scripting 
language developed under Unix, which is 
distributed under the GNU license and 
now runs on most platforms, including 
MacOS. it is the language of choice for 
11 nix system administration, CGI scripts 
and other goodies. More relevantly, it can 
really expand your ability to accomplish 
things on the Mac t In this article l describe 1 
a frustrating problem I had and a step by 
step Perl solution. I hope this example will 
encourage you to learn Perl and use it, 
Perl scripts are just text files and so are 
fairly easily portable across platforms 
making Perl even more useful if you need 
to solve the same problem on seven I 
platforms. Learning Perl is not difficult and 
it looks great on your resume, so why not 
give il a Iry? 


Mac: + Peri. = MacPerl 

Perl arouse because many UNIX 
programmers wanted a quick alternative to 
C, with many of Cs features. The result 
was a full featured, easy to use, C-like 
programming language. Perl has been 
ported to the Mac where it can l ie used to 
create pseudo-applications called droplets. 
1 call them pseudo because they do not 
have individual types and creators and so 
they must either be opened by double 


clicking or by dragging a document onto ihem. They are 
interpreted and so need the Perl interpreter in order to run. No 
Mac interface is needed to get information in or out, so Perl is 
ideal for projects that involve reading some data, analyzing ir, 
and outputting some conclusions, projects for which the evem- 
kx ip paradigm is more of an annoyance then a help (although 
Cmd-period will stop runaway Peri droplets). One can construct 
compiled applications with a full Mac interface, but the files arc 
large and the advantages over C largely evaporate. I use Perl for 
tasks as varied as extracting data from files to emailing students 
in a class their exam scores, 

Perl Ls “open source’’ software. The interpreter is available to 
download for free at <http;^/www.iis.ee.ethzxh/~neeri/macintosb/perl. 
or the I look “MaePerl, Power and Kase" by Vicki Brow n and Chris 
Nandor (#1-881957-32-2) from Prime Time Freeware <WWW.ptf,COm> 
contains a CD with the interpreter and lots of other useful stuff. The 
book itself is a nice introduction to programming in general and Perl 
in particular. Additional Perl stuff can be gleaned from die net. Try 
starting at <http;//www,perLcom>, 

Tint Problem 

Cot one of those cool digital cameras dial saves images to 
floppies? Then you know the files are labeled automatically, MVO 
01LJPG, MVC-02L.JPG, etc. Copy die images to your computer 
and you’re in business. But suppose you went wild and filled up 
two disks? Or ten? Piles on different floppies often have the same 
name, so you can’t just copy them to the same folder. So you copy 
one floppy, change all the names of the files, copy the second, etc 
- bummer Even with just a few- images, you tend to put them in 
;i folder with a useful name since otherwise you won't remember 
what the pictures arc about, can’t search for them with Sherlock, 
etc. Wouldn’t it lx: nice to have them named, whatever!.jpg, 
whatover2.jpg. etc,? 'fids is a perfect job for a script 

The script should begin with a folder named whatever and 
look inside il for all the MVC files anti rename them as 
whafever1.jpg, whatever2.jpg, etc. It should even be a bit smarter. 


Larry Taylor is a research mathematician and professor who spends too much time foaling around with this son of tiling. 
More si l iff al wwvvaxl.edu Art ay tor. 
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If there are going to Imj ten or more, the first should l>e 
whateverOt.jpg: if there are 100 or more, whateverOQljpg, if there 
are .. . but you gel the idea, Kven more, if there are already some 
whatever files, it should number the new MVC files to fit into the 
pattern. Specifically, it should look at the creation time of the 
first MVC file and the first whatever file. If the MVC time is later, 
tile MVC files should come after the whatever files, but otherwise 
the whatever files should lie renamed and the MVC files should 
come first. If the user trashed a few of the whatever files so they 
are no longer in sequence, the whatever files should be renamed 
so as to lie in sequence. 

Using this script, you cm copy one disk worth of images into 
a folder, run the script, copy the next disk, run the script, etc. At 
any time during the process, the images can l>e viewed and those 
that are unwanted can lie deleted.. At the end, ail of the “keepers" 
are named consecutively in the order in which they were taken, 
no matter the order in which they are copied or removed. 

The vScrift 

Open the MacPerl application and select New from the File 
menu and you're ready to start. Line 1 should l)e *!perl, This is 
a holdover from the Unix world where this line tells the 
operating system to feed this file to the Perl interpreter. You can 
also do things with it in MacPerl, but we don't here. Now save 
the file. Name it what you will. At the bottom of the dialog box 
is :\ pop up menu labeled Type:" (reading "Plain Text"). Set the 
menu to "Droplet" and save. 

The advantage of a droplet is that you can just drop items 
onto its icon anti the information is passed on to the script. In 
this script we include no other way to input folder/file 
information, although Perl can do so, even through standard file. 
The folder/file information is passed to the script as $ARGV[G]for 
the first folder/file, SARGVfl] for the second, etc. Droplets allow 
us to use the Mac GUI to mimic the command line paradigm. 
Dropping a collection of files on a droplet has the same effect 
as the command line, droplet_name Riel Rle2 ... 

Before discussing the code, here is an outline for solving 
the problem. 

Step 1: Get the folder name. If a folder is dropped, use it; if a 
file is dropped, use the enclosing folder. If several items are 
dropped, process them all. 

Step 2: Collect the names of the MVC files and die whatever files. 
Step 3: Get the two creation times and figure out die starting 
numbers for the two sets of files. 

Step 4: Rename the files. 

We do a certain amount of error checking and quit at the first 
sign of trouble - these may be your only photos of Aunt Rose. Perl 
borrows much from C, including die tendency to write short 
functions (subroutines in Perl). One immediate difference is die lack 
of variable typing (die same variable am be a number or a string, 
depending on context). Another is die ability to work with arrays 
whose size is unknown More execution. As a language, Perl is 
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particularly adept at manipulating arrays and strings and it does file 
management rather well 

Now For the code. We wriLe a sequence of subroutines 
most of which just do one of the steps outlined above and 
pass Lite relevant data on to the next. We try to introduce 
some interesting features of Perl in discussing each 
subroutine. More information can be gleaned from the code 
and its comments. Here is the first routine. The for loop 
works its way through the dropped items, passing each one 
in turn to the subroutine do a_folder which returns false if 
anything goes wrong. Ordinary Perl variable names start with 
$; arrays start with $#foo is Lhe last index of the array 
@foo. As with C the first array element is $foo[0]. If this were 
C the braces would be optional, but in Perl they are required. 

for (Si K=S#ARGV: $ii++> I # This is a Ft*tl eumraGnt, 

if(ldo_a_f older($ARGV|$til)) lexif:! 

t 

Perl handles file system objects via path names and the 
$ARGV variables are path names. The first line of the 
subroutine illustrates the way Perl passes variables to 
subroutines: the values are in a list/stack named ©_ and we 
can shift them off in order. The rest of the routine is 
straightforward. Perl has a simple syntax for checking if strings 
are folders or files, using two simple if" tests. One wrinkle 
here is that if you drop two MVC files on the droplet, by the 
time the second one is ready to be processed, ii no longer 
exists since it was renamed on the first pass. Tile routine does 
nothing in this case except return true, which is what we want. 
In short, this subroutine handles Step 1 for each dropped 
object and passes the results to the next subroutine. 

sub du_a_fotderi 
$ubJi?ct=shift (&_); 

if{ -f Sobjeet) [ fl r rhecks if Sobject Is a file. 

If It iget enclosing folder, 
$x~rindex{$abject,':'); # find LAST occurrence of : 

Sobject-substr(Sobject*U.; # remove lest part of 

# path name 

) 

# Sobject now path name to folder 

$x=rindex(Subject,':*); § find LAST occurrence uf : 

$£ oId_mime=subsir(Sobject,$x 1 i); If get naroe of folder 
If ( d Sobject] } # If" St a folder 
unlink[*$obj ec t:HAViCA, 1ITM ")i 

it This deletes a junk file which often getr, copied, 
return process folder ($object ■ Sfol<I_nuniu) : 

1 

# else quietly do nothing, 
return 1; 

I 

Extract the relevant files into two arrays. There is no need to 
specify the si/e of these arrays in adv ance since fieri handles these 
details. The undef’s make sure that these arrays are empty at the 
start. Explicitly initializing variables is usually a good idea. One 
outstanding feature of Perl is Unix regular expression matching 
and substitution. Look how easy it is to find the files we want: 

lf( $filesr$l]“Ta/'* , Sfold_nante\d‘ \.jpg$ /' 

This is true if die string on the left contains the expression 
Ixrtween the As. That expression says the string must begin (A) 


with $foid_name, have any number of digits (VI*) and then end 
($) with a .jpg. The dot is V Iiecause . means match any 
character. When we find a file of the desired type, the push puts 
it at the end of the appropriate array. Note that the elseif of C 
becomes eisif. Finally, die construction \@mvc_files is a way to 
pass a reference to the entire array to the nexi subroutine. 

sub proces(s_folder! 

$fold-«hlfL{*_): 

S f o 1 d„tiaEe=shi f t (#_): 

# Make sure names caifit too long for the Finder. 

$ f o ld_nan e=#*ibst r ($ f o t d _t i a use * f) . ?. 1): 
undef (@l’old_nanie_tlies); it Clear old values 
tmdef (@fold_name_files); it Clear old values 
tf{ npendir (DIR, $f old)) If/ if we can read the directory 
chdlrlSfold); H change the working directory 
@f lles=roadd i r (niFl; // read all objects into an array 
closedit{C|ttJ: clone the directory for reading 

fortSi = 0:$i< = $#III i $ H4 3 I 

iff $fiiesl$i]=^iii/*Srold ,tiaiae\d‘\. ]pg$/) t 

# remember the £ older _nf*mo files 
push(@fold_name„iilea.Sflies[$!]); 

I 

els I FC $fUenf$il— ra/^MVC Vd *I*\, JPG$/) I 

# remember lhe MVC files 
pusM@ntvc_f 1 las,$flies [$i| 3: 

I 

I 

if($#mvc files<0 && $#f old,jiame_Nlen<0) I 
return 1; # Nothing to do* 

1 

else l # Go rename the files, 
return ( 

setup_reiume(\|4H>vi _rilee.,A#fold name files * $fold_tiaEW?) ): 

I 

I 

nine ( print"Failed to open SfoldW': rtrtimi 0; I 


In die first few lines of the next subroutine, we retrieve the 
ivference to the arrays. The syntax is straightforward: in the 
previous subroutine ©mvcjiles was an array: in this subroutine the 
same array is ©Smvc files. There is no need to use lhe same name, 
Now look at the phrase: 

length ($/f$ fold name i rilen+1+$ mart Number) 

This is an example of how variable type changes: 
SffSfold name files is one less than the numlxr of tiles in the array 
@$fold^nameJiies so the sum is lhe biggest nuniter in a file name. 
The funciion length treats die number as a string and returns its 
length. If we have more than 9,999 files, we quit since then the 
file names might lx* longer lhan the Finder limit of 31 characters, 
fieri has builL-in functions to easily extract file information. 
We have no trouble getting creation limes: the function stat 
returns an array of data and the eleventh element in the array is 
the creation time. Remeiulxm the first is [0]. We then use this 
information to determine the starting number for lhe two sets of 
file names. This completes Step 3 and we pass the needed 
information on ro the next subroutine* 

sub setup_reRaint! t 
$mvc files^sbift: 

Sfold mm filefi'-fihlft {#_); 

$ f o 1 d _nantR-shl £t (§ ): 

yLatLNuniber=l: i The first file is numbered 1. 

$nev_d igi t_siz 0 ~T engf.h ( 

Sff$fold_nuBK. , _rn ^+$#$invc files+l+SetartNumber); 
if ($nev._digit„size>4) 

print‘’Mare than 9.999 files? No wayl\n": 
return l;jf Will process other folders 
I 

f 
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f Get MVC creation time (If possible) - 
iff ($#$folc nami* fi]efi>il) ) 1 

$time MVC-(atat {S$mvc_fi les [GJ)) 110]I 

I 

# Get foldei name creation time (if possible), 
if{$#$£□ ld_name_fliesS^O) I 

Stime_FH-(stat ($$fold narne filen [0])) [10] i 

# Calculate starting mimbnrs, 

if££f$i&ve filesCD) ( $fnt<l_naifte_starLNumber-$3tortNumber? 3 
elsif($f$fold na»o_fllea<0) I$mvc_sisriNumber-$sta£tNumbef;I 
el r J f ($t Tmo„HVC<$tiwe_b'N) I 
$mvc _s t a r L Nunber=$sta rtNumbe t: 

$£ol(I_name_startNiiitLbe t-$J$mvc fi les +1 +$$ta rtNtmbcr: 

1 

else I 

$mvc_staxtNumber=$//$fol rl _nmnc_f 31 eu+i+SstartNumber: 

Sfold name stsr rNumbc r^sLu ti Number; 

I 

retdf n r on«w.'_ f 11 es ($mvc_i lies. $myc_siartNumber * 

$ f a 1 d „nante„files.$ t o id_name start Numbe r. 
$fald_r!ane«$r)ew_diglt_size); 

1 


The rename routine (Step 4) is ;i hit more complicated. The 
Perl rename routine is a Unix style routine, so if there already is 
a file with the new name, the old file is destroyed without 
warning- The Mac solution is better, but annoying - put up a 
dialog Ixjx and let the user recover. But you don’t want dialog 
boxes, you just want the files renamed. The solution we use is 
to create a temporary folder, move the tiles into this folder as we 
rename them, move them back when we are done, and finally, 
delete the temporary foldei We put this temporary' folder in our 
enclosing folder so that in the event of an emir it should be easy 
to find all your files. 

Here we introduce another way to collect the information 
passed as the aigumems: make a list on the left and set it equal to 
@ The mkdir, rmdir functions betray their 1 nix heritage. Subroutines 
move the files into the temporary folder and out of il again. 

sub renarae_f:iies I 

# Make temporary folder - the name will be a number 
$dir-0; 

while( -d $dir || -f $d1r ) l$dlr++{i 

I Possible infinite loop but need thousands of 
folderrt/f 3 lee with numbers as names .Don*t worry. 

If £!mkd1rl$dir,0///J) [ 

print"Polled to make temporary folder. \ii" i 
return 0: 

1 

($fHesA,$fitflrtA f $£ilesB»$fitsrrB f Spreflx,$digit_alse)^@_; 

$di r_pref ix=“: $<lir: $pref t x"; 

# Hove the first batch of files* then the second. 

Ball If error. 

iff Imv_ImpCSuLurtA.SiilesA,$dir_prefix.Sdigit size ))i 
return 0; 

1 

if {lmv_tmpt$start& f $filesB,$dir ptef tx*$d 1 glL_slzt*)) 
return 0: 

I 

# move the files hack. Boil if error, 
ifftmv hark ($d t r) } j reLurri 0:! 
t Delete the icBparary directory 
return rmdir($dir): 

1 

Nothing much new in the next subroutine except the breach 
loop. This works through the array setting $h to the values of the 
array in older - no need for an index variable. This is not 
eanhshafcing, but elegant. The s routine completes the script 


sub rav^iaipl 

£$firni,$1isL.Sd1r_prefix.$dlgitSize) 
foreach $h {e$list) i 

$numStr=uiibstr ['*00000’’,0,$digitSize-leri£th{$firat)) .$nrat: 
It(Jrename{$h."3dlr prffflx3numKn.jpg") )1 
print “Failed to move $ii I file: SdifVo**T 
return 0; 
l 

$fIrnt H-■ 

I 

return 1; 

I 

sub :nv_backl 

$dir=shift£# )i 

if(upendir(DIR.$dIf) )| 

ftfUas=rnadd,1 r(niR); jj read all uhjects into an array 
closed i r(JlIR): # tlose the directory for reading 

chdtr($dir); 
foreaeh $h (Stiles) I 
if{!rename($h.:$h") )< 

print “Failed to move $h out oE $dir\n’ ,P : 
return 0; 

1 

J 

cMlrt**:"): 
return 1; 

1 

else [return 0:1 

1 


Final Comments 

The constructions, syntax and built-in ftimlioas discussed in 
this short article have barely scratched the surface of what is 
available. And more is coining every day. See <http://wVkWiperl.com> 
and related links. 1 hope this example will spark your interest in 
using Perl for your own projects. Happy scripting. 
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